job-shop-lib 1.3.0__py3-none-any.whl → 1.6.0__py3-none-any.whl

job_shop_lib/__init__.py

@@ -19,7 +19,7 @@ from job_shop_lib._schedule import Schedule
 from job_shop_lib._base_solver import BaseSolver, Solver
 
 
-__version__ = "1.3.0"
+__version__ = "1.6.0"
 
 __all__ = [
     "Operation",

job_shop_lib/_base_solver.py

@@ -15,13 +15,13 @@ Solver = Callable[[JobShopInstance], Schedule]
 class BaseSolver(abc.ABC):
     """Base class for all solvers implemented as classes.
 
-    A `Solver` is any `Callable` that takes a `JobShopInstance` and returns a
-    `Schedule`. Therefore, solvers can be implemented as functions or as
-    classes. This class is provided as a base class for solvers implemented as
-    classes. It provides a default implementation of the `__call__` method that
-    measures the time taken to solve the instance and stores it in the
-    schedule's metadata under the key "elapsed_time" if it is not already
-    present.
+    A ``Solver`` is any ``Callable`` that takes a :class:`JobShopInstance` and
+    returns a :class:`Schedule`. Therefore, solvers can be implemented as
+    functions or as classes. This class is provided as a base class for solvers
+    implemented as classes. It provides a default implementation of the
+    ``__call__`` method that measures the time taken to solve the instance
+    and stores it in the schedule's metadata under the key "elapsed_time" if
+    it is not alreadypresent.
     """
 
     @abc.abstractmethod

job_shop_lib/_job_shop_instance.py

@@ -3,8 +3,10 @@
 from __future__ import annotations
 
 import os
+from collections.abc import Sequence
 import functools
 from typing import Any
+import warnings
 
 import numpy as np
 from numpy.typing import NDArray
@@ -40,6 +42,9 @@ class JobShopInstance:
         is_flexible
         durations_matrix
         machines_matrix
+        release_dates_matrix
+        deadlines_matrix
+        due_dates_matrix
         durations_matrix_array
         machines_matrix_array
         operations_by_machine
@@ -92,6 +97,24 @@ class JobShopInstance:
         self.name: str = name
         self.metadata: dict[str, Any] = metadata
 
+        deprecated_keys = {
+            "release_dates_matrix",
+            "deadlines_matrix",
+            "due_dates_matrix",
+        }
+        if any(key in self.metadata for key in deprecated_keys):
+            warnings.warn(
+                "The use of 'release_dates_matrix', 'deadlines_matrix', or "
+                "'due_dates_matrix' in metadata is deprecated."
+                "Please add these attributes "
+                "directly to the Operation class. Not doing so may cause bugs "
+                "when using the dispatching module.You can use the "
+                "`JobShopInstance.from_matrices` method to create an "
+                "instance from 2D sequences. ",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
     def set_operation_attributes(self):
         """Sets the ``job_id``, ``position_in_job``, and ``operation_id``
         attributes for each operation in the instance.
@@ -196,14 +219,25 @@ class JobShopInstance:
                     "duration_matrix": self.durations_matrix,
                     "machines_matrix": self.machines_matrix,
                     "metadata": self.metadata,
+                    # Optionally (if the instance has them):
+                    "release_dates_matrix": self.release_dates_matrix,
+                    "deadlines_matrix": self.deadlines_matrix,
+                    "due_dates_matrix": self.due_dates_matrix,
                 }
         """
-        return {
+        data = {
             "name": self.name,
             "duration_matrix": self.durations_matrix,
             "machines_matrix": self.machines_matrix,
             "metadata": self.metadata,
         }
+        if self.has_release_dates:
+            data["release_dates_matrix"] = self.release_dates_matrix
+        if self.has_deadlines:
+            data["deadlines_matrix"] = self.deadlines_matrix
+        if self.has_due_dates:
+            data["due_dates_matrix"] = self.due_dates_matrix
+        return data
 
     @classmethod
     def from_matrices(
@@ -212,6 +246,9 @@ class JobShopInstance:
         machines_matrix: list[list[list[int]]] | list[list[int]],
         name: str = "JobShopInstance",
         metadata: dict[str, Any] | None = None,
+        release_dates_matrix: list[list[int]] | None = None,
+        deadlines_matrix: list[list[int | None]] | None = None,
+        due_dates_matrix: list[list[int | None]] | None = None,
     ) -> JobShopInstance:
         """Creates a :class:`JobShopInstance` from duration and machines
         matrices.
@@ -219,16 +256,26 @@ class JobShopInstance:
         Args:
             duration_matrix:
                 A list of lists of integers. The i-th list contains the
-                durations of the operations of the job with id i.
+                durations of the operations of the job with id ``i``.
             machines_matrix:
                 A list of lists of lists of integers if the
                 instance is flexible, or a list of lists of integers if the
                 instance is not flexible. The i-th list contains the machines
-                in which the operations of the job with id i can be processed.
+                in which the operations of the job with id ``i`` can be
+                processed.
             name:
                 A string with the name of the instance.
             metadata:
                 A dictionary with additional information about the instance.
+            release_dates_matrix:
+                A list of lists of integers. The i-th list contains the
+                release dates of the operations of the job with id ``i``.
+            deadlines_matrix:
+                A list of lists of optional integers. The i-th list contains
+                the deadlines of the operations of the job with id ``i``.
+            due_dates_matrix:
+                A list of lists of optional integers. The i-th list contains
+                the due dates of the operations of the job with id ``i``.
 
         Returns:
             A :class:`JobShopInstance` object.
@@ -241,8 +288,29 @@ class JobShopInstance:
             for position_in_job in range(num_operations):
                 duration = duration_matrix[job_id][position_in_job]
                 machines = machines_matrix[job_id][position_in_job]
+                release_date = (
+                    release_dates_matrix[job_id][position_in_job]
+                    if release_dates_matrix
+                    else 0
+                )
+                deadline = (
+                    deadlines_matrix[job_id][position_in_job]
+                    if deadlines_matrix
+                    else None
+                )
+                due_date = (
+                    due_dates_matrix[job_id][position_in_job]
+                    if due_dates_matrix
+                    else None
+                )
                 jobs[job_id].append(
-                    Operation(duration=duration, machines=machines)
+                    Operation(
+                        duration=duration,
+                        machines=machines,
+                        release_date=release_date,
+                        deadline=deadline,
+                        due_date=due_date,
+                    )
                 )
 
         metadata = {} if metadata is None else metadata
@@ -289,6 +357,21 @@ class JobShopInstance:
             for job in self.jobs
         )
 
+    @functools.cached_property
+    def has_release_dates(self) -> bool:
+        """Returns ``True`` if any operation has a release date > 0."""
+        return any(op.release_date > 0 for job in self.jobs for op in job)
+
+    @functools.cached_property
+    def has_deadlines(self) -> bool:
+        """Returns ``True`` if any operation has a deadline."""
+        return any(op.deadline is not None for job in self.jobs for op in job)
+
+    @functools.cached_property
+    def has_due_dates(self) -> bool:
+        """Returns ``True`` if any operation has a due date."""
+        return any(op.due_date is not None for job in self.jobs for op in job)
+
     @functools.cached_property
     def durations_matrix(self) -> list[list[int]]:
         """Returns the duration matrix of the instance.
@@ -330,23 +413,75 @@ class JobShopInstance:
             [operation.machine_id for operation in job] for job in self.jobs
         ]
 
+    @functools.cached_property
+    def release_dates_matrix(self) -> list[list[int]]:
+        """Returns the release dates matrix of the instance.
+
+        The release date 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.
+        """
+        return [
+            [operation.release_date for operation in job] for job in self.jobs
+        ]
+
+    @functools.cached_property
+    def deadlines_matrix(self) -> list[list[int | None]]:
+        """Returns the deadlines matrix of the instance.
+
+        The deadline 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.
+        """
+        return [[operation.deadline for operation in job] for job in self.jobs]
+
+    @functools.cached_property
+    def due_dates_matrix(self) -> list[list[int | None]]:
+        """Returns the due dates matrix of the instance.
+
+        The due date 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.
+        """
+        return [[operation.due_date for operation in job] for job in self.jobs]
+
     @functools.cached_property
     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``.
+        If the jobs have different number of operations, the matrix is
+        padded with ``np.nan`` to make it rectangular.
+        """
+        return self._fill_matrix_with_nans_2d(self.durations_matrix)
 
-        Example:
-            >>> jobs = [[Operation(0, 2), Operation(1, 3)], [Operation(0, 4)]]
-            >>> instance = JobShopInstance(jobs)
-            >>> instance.durations_matrix_array
-            array([[ 2.,  3.],
-                   [ 4., nan]], dtype=float32)
+    @functools.cached_property
+    def release_dates_matrix_array(self) -> NDArray[np.float32]:
+        """Returns the release dates matrix of the instance as a numpy array.
+
+        If the jobs have different number of operations, the matrix is
+        padded with ``np.nan`` to make it rectangular.
         """
-        duration_matrix = self.durations_matrix
-        return self._fill_matrix_with_nans_2d(duration_matrix)
+        return self._fill_matrix_with_nans_2d(self.release_dates_matrix)
+
+    @functools.cached_property
+    def deadlines_matrix_array(self) -> NDArray[np.float32]:
+        """Returns the deadlines matrix of the instance as a numpy array.
+
+        If the jobs have different number of operations, the matrix is
+        padded with ``np.nan`` to make it rectangular. None values are also
+        converted to ``np.nan``.
+        """
+        return self._fill_matrix_with_nans_2d(self.deadlines_matrix)
+
+    @functools.cached_property
+    def due_dates_matrix_array(self) -> NDArray[np.float32]:
+        """Returns the due dates matrix of the instance as a numpy array.
+
+        If the jobs have different number of operations, the matrix is
+        padded with ``np.nan`` to make it rectangular. None values are also
+        converted to ``np.nan``.
+        """
+        return self._fill_matrix_with_nans_2d(self.due_dates_matrix)
 
     @functools.cached_property
     def machines_matrix_array(self) -> NDArray[np.float32]:
@@ -474,13 +609,13 @@ class JobShopInstance:
 
     @staticmethod
     def _fill_matrix_with_nans_2d(
-        matrix: list[list[int]],
+        matrix: Sequence[Sequence[int | None]],
     ) -> NDArray[np.float32]:
-        """Fills a matrix with ``np.nan`` values.
+        """Creates a 2D numpy array padded with ``np.nan`` values.
 
         Args:
             matrix:
-                A list of lists of integers.
+                A list of lists of integers or Nones.
 
         Returns:
             A numpy array with the same shape as the input matrix, filled with
@@ -491,14 +626,17 @@ class JobShopInstance:
             (len(matrix), max_length), np.nan, dtype=np.float32
         )
         for i, row in enumerate(matrix):
-            squared_matrix[i, : len(row)] = row
+            processed_row = [
+                item if item is not None else np.nan for item in row
+            ]
+            squared_matrix[i, : len(processed_row)] = processed_row
         return squared_matrix
 
     @staticmethod
     def _fill_matrix_with_nans_3d(
         matrix: list[list[list[int]]],
     ) -> NDArray[np.float32]:
-        """Fills a 3D matrix with ``np.nan`` values.
+        """Creates a 3D numpy array padded with ``np.nan`` values.
 
         Args:
             matrix:
@@ -522,9 +660,3 @@ 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

@@ -30,6 +30,16 @@ class Operation:
             an integer.
         duration:
             The time it takes to perform the operation.
+        release_date:
+            The earliest moment this operation can be scheduled to start.
+            Defaults to ``0``.
+        deadline:
+            A hard cutoff time by which the job must be finished. A schedule
+            is invalid if the job completes after this time. Defaults to
+            ``None``.
+        due_date:
+            The target completion time for the job. Finishing late is allowed
+            but incurs a penalty (e.g., tardiness). Defaults to ``None``.
     """
 
     __slots__ = {
@@ -42,6 +52,20 @@ class Operation:
             "The time it takes to perform the operation. Often referred"
             " to as the processing time."
         ),
+        "release_date": (
+            "The earliest moment this operation can be scheduled to start. "
+            "Defaults to ``0``."
+        ),
+        "deadline": (
+            "A hard cutoff time by which the job must be finished. A schedule "
+            "is invalid if the job completes after this time. Defaults to "
+            "``None``."
+        ),
+        "due_date": (
+            "The target completion time for the job. Finishing late is "
+            "allowed but incurs a penalty (e.g., tardiness). Defaults to "
+            "``None``."
+        ),
         "job_id": (
             "The id of the job the operation belongs to. Defaults to -1. "
             "It is usually set by the :class:`JobShopInstance` class after "
@@ -59,11 +83,21 @@ class Operation:
         ),
     }
 
-    def __init__(self, machines: int | list[int], duration: int):
+    def __init__(
+        self,
+        machines: int | list[int],
+        duration: int,
+        release_date: int = 0,
+        deadline: int | None = None,
+        due_date: int | None = None,
+    ):
         self.machines: list[int] = (
             [machines] if isinstance(machines, int) else machines
         )
         self.duration: int = duration
+        self.release_date: int = release_date
+        self.deadline: int | None = deadline
+        self.due_date: int | None = due_date
 
         # Defined outside the class by the JobShopInstance class:
         self.job_id: int = -1
@@ -93,9 +127,9 @@ class Operation:
     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
+            self.job_id != -1
+            and self.position_in_job != -1
+            and self.operation_id != -1
         )
 
     def __hash__(self) -> int:
@@ -104,7 +138,16 @@ class Operation:
     def __eq__(self, value: object) -> bool:
         if not isinstance(value, Operation):
             return False
-        return self.__slots__ == value.__slots__
+        return (
+            self.machines == value.machines
+            and self.duration == value.duration
+            and self.release_date == value.release_date
+            and self.deadline == value.deadline
+            and self.due_date == value.due_date
+            and self.job_id == value.job_id
+            and self.position_in_job == value.position_in_job
+            and self.operation_id == value.operation_id
+        )
 
     def __repr__(self) -> str:
         machines = (

job_shop_lib/_schedule.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 from typing import Any, TYPE_CHECKING
 from collections import deque
 
-from job_shop_lib import ScheduledOperation, JobShopInstance
+from job_shop_lib import ScheduledOperation, JobShopInstance, Operation
 from job_shop_lib.exceptions import ValidationError
 
 if TYPE_CHECKING:
@@ -53,6 +53,19 @@ class Schedule:
             "schedule. It can be used to store information about the "
             "algorithm that generated the schedule, for example."
         ),
+        "operation_to_scheduled_operation": (
+            "A dictionary that maps an :class:`Operation` to its "
+            ":class:`ScheduledOperation` in the schedule. This is used to "
+            "quickly find the scheduled operation associated with a given "
+            "operation."
+        ),
+        "num_scheduled_operations": (
+            "The number of operations that have been scheduled so far."
+        ),
+        "operation_with_latest_end_time": (
+            "The :class:`ScheduledOperation` with the latest end time. "
+            "This is used to quickly find the last operation in the schedule."
+        ),
     }
 
     def __init__(
@@ -69,6 +82,25 @@ class Schedule:
         self.instance: JobShopInstance = instance
         self._schedule = schedule
         self.metadata: dict[str, Any] = metadata
+        self.operation_to_scheduled_operation: dict[
+            Operation, ScheduledOperation
+        ] = {
+            scheduled_op.operation: scheduled_op
+            for machine_schedule in schedule
+            for scheduled_op in machine_schedule
+        }
+        self.num_scheduled_operations = sum(
+            len(machine_schedule) for machine_schedule in schedule
+        )
+        self.operation_with_latest_end_time: ScheduledOperation | None = max(
+            (
+                scheduled_op
+                for machine_schedule in schedule
+                for scheduled_op in machine_schedule
+            ),
+            key=lambda op: op.end_time,  # type: ignore[union-attr]
+            default=None,
+        )
 
     def __repr__(self) -> str:
         return str(self.schedule)
@@ -84,11 +116,6 @@ class Schedule:
         Schedule.check_schedule(new_schedule)
         self._schedule = new_schedule
 
-    @property
-    def num_scheduled_operations(self) -> int:
-        """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:
         """Returns a dictionary representation of the schedule.
 
@@ -106,15 +133,9 @@ class Schedule:
                 - **"metadata"**: A dictionary with additional information
                   about the schedule.
         """
-        job_sequences: list[list[int]] = []
-        for machine_schedule in self.schedule:
-            job_sequences.append(
-                [operation.job_id for operation in machine_schedule]
-            )
-
         return {
             "instance": self.instance.to_dict(),
-            "job_sequences": job_sequences,
+            "job_sequences": self.job_sequences(),
             "metadata": self.metadata,
         }
 
@@ -211,20 +232,35 @@ class Schedule:
                 )
         return dispatcher.schedule
 
+    def job_sequences(self) -> list[list[int]]:
+        """Returns the sequence of jobs for each machine in the schedule.
+
+        This method returns a list of lists, where each sublist contains the
+        job ids of the operations scheduled on that machine.
+        """
+        job_sequences: list[list[int]] = []
+        for machine_schedule in self.schedule:
+            job_sequences.append(
+                [operation.job_id for operation in machine_schedule]
+            )
+        return job_sequences
+
     def reset(self):
         """Resets the schedule to an empty state."""
         self.schedule = [[] for _ in range(self.instance.num_machines)]
+        self.operation_to_scheduled_operation = {}
+        self.num_scheduled_operations = 0
+        self.operation_with_latest_end_time = None
 
     def makespan(self) -> int:
         """Returns the makespan of the schedule.
 
         The makespan is the time at which all operations are completed.
         """
-        max_end_time = 0
-        for machine_schedule in self.schedule:
-            if machine_schedule:
-                max_end_time = max(max_end_time, machine_schedule[-1].end_time)
-        return max_end_time
+        last_operation = self.operation_with_latest_end_time
+        if last_operation is None:
+            return 0
+        return last_operation.end_time
 
     def is_complete(self) -> bool:
         """Returns ``True`` if all operations have been scheduled."""
@@ -245,10 +281,25 @@ class Schedule:
                 constraints.
         """
         self._check_start_time_of_new_operation(scheduled_operation)
+
+        # Update attributes:
         self.schedule[scheduled_operation.machine_id].append(
             scheduled_operation
         )
 
+        self.operation_to_scheduled_operation[
+            scheduled_operation.operation
+        ] = scheduled_operation
+
+        self.num_scheduled_operations += 1
+
+        if (
+            self.operation_with_latest_end_time is None
+            or scheduled_operation.end_time
+            > self.operation_with_latest_end_time.end_time
+        ):
+            self.operation_with_latest_end_time = scheduled_operation
+
     def _check_start_time_of_new_operation(
         self,
         new_operation: ScheduledOperation,
@@ -333,3 +384,71 @@ class Schedule:
             [machine_schedule.copy() for machine_schedule in self.schedule],
             **self.metadata,
         )
+
+    def critical_path(self) -> list[ScheduledOperation]:
+        """Returns the critical path of the schedule.
+
+        The critical path is the longest path of dependent operations through
+        the schedule, which determines the makespan. This implementation
+        correctly identifies the path even in non-compact schedules where
+        idle time may exist.
+
+        It works by starting from an operation that determines the makespan
+        and tracing backwards, at each step choosing the predecessor (either
+        from the same job or the same machine) that finished latest.
+        """
+        # 1. Start from the operation that determines the makespan
+        last_scheduled_op = self.operation_with_latest_end_time
+        if last_scheduled_op is None:
+            return []
+
+        critical_path = deque([last_scheduled_op])
+        current_scheduled_op = last_scheduled_op
+
+        # 2. Trace backwards from the last operation
+        while True:
+            job_pred = None
+            machine_pred = None
+
+            # Find job predecessor (the previous operation in the same job)
+            op_idx_in_job = current_scheduled_op.operation.position_in_job
+            if op_idx_in_job > 0:
+                prev_op_in_job = self.instance.jobs[
+                    current_scheduled_op.job_id
+                ][op_idx_in_job - 1]
+                job_pred = self.operation_to_scheduled_operation[
+                    prev_op_in_job
+                ]
+
+            # Find machine predecessor (the previous operation on the same
+            # machine)
+            machine_schedule = self.schedule[current_scheduled_op.machine_id]
+            op_idx_on_machine = machine_schedule.index(current_scheduled_op)
+            if op_idx_on_machine > 0:
+                machine_pred = machine_schedule[op_idx_on_machine - 1]
+
+            # 3. Determine the critical predecessor
+            # The critical predecessor is the one that finished latest, as it
+            # determined the start time of the current operation.
+
+            if job_pred is None and machine_pred is None:
+                # Reached the beginning of the schedule, no more predecessors
+                break
+
+            job_pred_end_time = (
+                job_pred.end_time if job_pred is not None else -1
+            )
+            machine_pred_end_time = (
+                machine_pred.end_time if machine_pred is not None else -1
+            )
+            critical_pred = (
+                job_pred
+                if job_pred_end_time >= machine_pred_end_time
+                else machine_pred
+            )
+            assert critical_pred is not None
+            # Prepend the critical predecessor to the path and continue tracing
+            critical_path.appendleft(critical_pred)
+            current_scheduled_op = critical_pred
+
+        return list(critical_path)

job_shop_lib/constraint_programming/_ortools_solver.py

@@ -112,16 +112,12 @@ class ORToolsSolver(BaseSolver):
         problem.
 
         Args:
-            instance:
-                The job shop instance to be solved.
-            arrival_times:
-                Optional arrival times for each operation.
-                If provided, the solver will ensure that operations do not
-                start before their respective arrival times.
-            deadlines:
-                Optional deadlines for each operation.
-                If provided, the solver will ensure that operations are
-                completed before their respective deadlines.
+            instance: The job shop instance to be solved.
+
+            .. note::
+                If provided, `arrival_times` and `deadlines` will override the
+                `release_date` and `deadline` attributes of the operations,
+                respectively.
 
         Returns:
             The best schedule found by the solver.
@@ -225,9 +221,12 @@ class ORToolsSolver(BaseSolver):
         """Creates two variables for each operation: start and end time."""
         for job in instance.jobs:
             for operation in job:
-                # Initial Naive Bounds
-                lower_bound = 0
-                upper_bound = instance.total_duration
+                lower_bound = operation.release_date
+                upper_bound = (
+                    instance.total_duration
+                    if operation.deadline is None
+                    else operation.deadline
+                )
 
                 if arrival_times is not None:
                     lower_bound = arrival_times[operation.job_id][