job-shop-lib 0.4.0__tar.gz → 0.5.1__tar.gz

{job_shop_lib-0.4.0 → job_shop_lib-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: job-shop-lib
-Version: 0.4.0
+Version: 0.5.1
 Summary: An easy-to-use and modular Python library for the Job Shop Scheduling Problem (JSSP)
 License: MIT
 Author: Pabloo22
@@ -15,7 +15,8 @@ Provides-Extra: pygraphviz
 Requires-Dist: imageio (>=2,<3)
 Requires-Dist: matplotlib (>=3,<4)
 Requires-Dist: networkx (>=3,<4)
-Requires-Dist: ortools (>=9,<10)
+Requires-Dist: numpy (>=1.26.4,<2.0.0)
+Requires-Dist: ortools (>=9.9,<9.10)
 Requires-Dist: pyarrow (>=15.0.0,<16.0.0)
 Requires-Dist: pygraphviz (>=1.12,<2.0) ; extra == "pygraphviz"
 Description-Content-Type: text/markdown
@@ -83,7 +84,7 @@ ft06 = load_benchmark_instance("ft06")
 ```
 
 The module `benchmarks` contains functions to load the instances from the file and return them as `JobShopInstance` objects without having to download them
-manually. The instances are stored in [benchmark_instances.json](job_shop_lib/benchmarks/benchmark_instances.json).
+manually.
 
 The contributions to this benchmark dataset are as follows:
 
@@ -171,13 +172,15 @@ class DispatchingRule(str, Enum):
 We can visualize the solution with a `DispatchingRuleSolver` as a gif:
 
 ```python
-from job_shop_lib.visualization import create_gif, get_plot_function
+from job_shop_lib.visualization import create_gif, plot_gantt_chart_wrapper
 from job_shop_lib.dispatching import DispatchingRuleSolver, DispatchingRule
 
 plt.style.use("ggplot")
 
 mwkr_solver = DispatchingRuleSolver("most_work_remaining")
-plot_function = get_plot_function(title="Solution with Most Work Remaining Rule")
+plot_function = plot_gantt_chart_wrapper(
+    title="Solution with Most Work Remaining Rule"
+)
 create_gif(
     gif_path="ft06_optimized.gif",
     instance=ft06,
@@ -350,3 +353,4 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
      Journal of Operational Research, vol. 64, no. 2, pp. 278–285, 1993.
 
 - Park, Junyoung, Sanjar Bakhtiyar, and Jinkyoo Park. "ScheduleNet: Learn to solve multi-agent scheduling problems with reinforcement learning." arXiv preprint arXiv:2106.03051, 2021. 
+

{job_shop_lib-0.4.0 → job_shop_lib-0.5.1}/README.md

@@ -61,7 +61,7 @@ ft06 = load_benchmark_instance("ft06")
 ```
 
 The module `benchmarks` contains functions to load the instances from the file and return them as `JobShopInstance` objects without having to download them
-manually. The instances are stored in [benchmark_instances.json](job_shop_lib/benchmarks/benchmark_instances.json).
+manually.
 
 The contributions to this benchmark dataset are as follows:
 
@@ -149,13 +149,15 @@ class DispatchingRule(str, Enum):
 We can visualize the solution with a `DispatchingRuleSolver` as a gif:
 
 ```python
-from job_shop_lib.visualization import create_gif, get_plot_function
+from job_shop_lib.visualization import create_gif, plot_gantt_chart_wrapper
 from job_shop_lib.dispatching import DispatchingRuleSolver, DispatchingRule
 
 plt.style.use("ggplot")
 
 mwkr_solver = DispatchingRuleSolver("most_work_remaining")
-plot_function = get_plot_function(title="Solution with Most Work Remaining Rule")
+plot_function = plot_gantt_chart_wrapper(
+    title="Solution with Most Work Remaining Rule"
+)
 create_gif(
     gif_path="ft06_optimized.gif",
     instance=ft06,
@@ -327,4 +329,4 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
  - E. Taillard, "Benchmarks for basic scheduling problems," European
      Journal of Operational Research, vol. 64, no. 2, pp. 278–285, 1993.
 
-- Park, Junyoung, Sanjar Bakhtiyar, and Jinkyoo Park. "ScheduleNet: Learn to solve multi-agent scheduling problems with reinforcement learning." arXiv preprint arXiv:2106.03051, 2021. 
+- Park, Junyoung, Sanjar Bakhtiyar, and Jinkyoo Park. "ScheduleNet: Learn to solve multi-agent scheduling problems with reinforcement learning." arXiv preprint arXiv:2106.03051, 2021. 

{job_shop_lib-0.4.0 → job_shop_lib-0.5.1}/job_shop_lib/dispatching/dispatcher.py

@@ -19,13 +19,45 @@ from job_shop_lib import (
 
 # Added here to avoid circular imports
 class DispatcherObserver(abc.ABC):
-    """Interface for classes that observe the dispatcher."""
+    """Interface for classes that observe th"""
+
+    def __init__(
+        self,
+        dispatcher: Dispatcher,
+        is_singleton: bool = True,
+        subscribe: bool = True,
+    ):
+        """Initializes the observer with the `Dispatcher` and subscribes to
+        it.
+
+        Args:
+            subject:
+                The subject to observe.
+            is_singleton:
+                Whether the observer should be a singleton. If True, the
+                observer will be the only instance of its class in the
+                subject's list of subscribers. If False, the observer will
+                be added to the subject's list of subscribers every time
+                it is initialized.
+            subscribe:
+                Whether to subscribe the observer to the subject. If False,
+                the observer will not be subscribed to the subject and will
+                not receive automatic updates.
+        """
+        if is_singleton and any(
+            isinstance(observer, self.__class__)
+            for observer in dispatcher.subscribers
+        ):
+            raise ValueError(
+                f"An observer of type {self.__class__.__name__} already "
+                "exists in the dispatcher's list of subscribers. If you want "
+                "to create multiple instances of this observer, set "
+                "`is_singleton` to False."
+            )
 
-    def __init__(self, dispatcher: Dispatcher):
-        """Initializes the observer with the dispatcher and subscribes to
-        it."""
         self.dispatcher = dispatcher
-        self.dispatcher.subscribe(self)
+        if subscribe:
+            self.dispatcher.subscribe(self)
 
     @abc.abstractmethod
     def update(self, scheduled_operation: ScheduledOperation):
@@ -39,7 +71,7 @@ class DispatcherObserver(abc.ABC):
         return self.__class__.__name__
 
     def __repr__(self) -> str:
-        return str(self)
+        return self.__class__.__name__
 
 
 def _dispatcher_cache(method):
@@ -86,8 +118,6 @@ class Dispatcher:
         pruning_function:
             A function that filters out operations that are not ready to be
             scheduled.
-        subscribers:
-            A list of observers that are subscribed to the dispatcher.
     """
 
     __slots__ = (
@@ -152,32 +182,6 @@ class Dispatcher:
         """Returns the next available time for each job."""
         return self._job_next_available_time
 
-    @classmethod
-    def create_schedule_from_raw_solution(
-        cls, instance: JobShopInstance, raw_solution: list[list[Operation]]
-    ) -> Schedule:
-        """Deprecated method, use `Schedule.from_job_sequences` instead."""
-        warn(
-            "Dispatcher.create_schedule_from_raw_solution is deprecated. "
-            "Use Schedule.from_job_sequences instead. It will be removed in "
-            "version 1.0.0.",
-            DeprecationWarning,
-        )
-        dispatcher = cls(instance)
-        dispatcher.reset()
-        raw_solution_deques = [
-            deque(operations) for operations in raw_solution
-        ]
-        while not dispatcher.schedule.is_complete():
-            for machine_id, operations in enumerate(raw_solution_deques):
-                if not operations:
-                    continue
-                operation = operations[0]
-                if dispatcher.is_operation_ready(operation):
-                    dispatcher.dispatch(operation, machine_id)
-                    operations.popleft()
-        return dispatcher.schedule
-
     def subscribe(self, observer: DispatcherObserver):
         """Subscribes an observer to the dispatcher."""
         self.subscribers.append(observer)
@@ -304,20 +308,6 @@ class Dispatcher:
                 min_start_time = min(min_start_time, start_time)
         return int(min_start_time)
 
-    @_dispatcher_cache
-    def uncompleted_operations(self) -> list[Operation]:
-        """Returns the list of operations that have not been scheduled.
-
-        An operation is uncompleted if it has not been scheduled yet.
-
-        It is more efficient than checking all operations in the instance.
-        """
-        uncompleted_operations = []
-        for job_id, next_position in enumerate(self._job_next_operation_index):
-            operations = self.instance.jobs[job_id][next_position:]
-            uncompleted_operations.extend(operations)
-        return uncompleted_operations
-
     @_dispatcher_cache
     def available_operations(self) -> list[Operation]:
         """Returns a list of available operations for processing, optionally
@@ -330,15 +320,22 @@ class Dispatcher:
         Returns:
             A list of Operation objects that are available for scheduling.
         """
-
-        available_operations = self._available_operations()
+        available_operations = self.available_operations_without_pruning()
         if self.pruning_function is not None:
             available_operations = self.pruning_function(
                 self, available_operations
             )
         return available_operations
 
-    def _available_operations(self) -> list[Operation]:
+    @_dispatcher_cache
+    def available_operations_without_pruning(self) -> list[Operation]:
+        """Returns a list of available operations for processing without
+        applying the pruning function.
+
+        Returns:
+            A list of Operation objects that are available for scheduling
+            based on precedence and machine constraints only.
+        """
         available_operations = []
         for job_id, next_position in enumerate(self._job_next_operation_index):
             if next_position == len(self.instance.jobs[job_id]):
@@ -346,3 +343,174 @@ class Dispatcher:
             operation = self.instance.jobs[job_id][next_position]
             available_operations.append(operation)
         return available_operations
+
+    @_dispatcher_cache
+    def unscheduled_operations(self) -> list[Operation]:
+        """Returns the list of operations that have not been scheduled."""
+        unscheduled_operations = []
+        for job_id, next_position in enumerate(self._job_next_operation_index):
+            operations = self.instance.jobs[job_id][next_position:]
+            unscheduled_operations.extend(operations)
+        return unscheduled_operations
+
+    @_dispatcher_cache
+    def scheduled_operations(self) -> list[Operation]:
+        """Returns the list of operations that have been scheduled."""
+        scheduled_operations = []
+        for job_id, next_position in enumerate(self._job_next_operation_index):
+            operations = self.instance.jobs[job_id][:next_position]
+            scheduled_operations.extend(operations)
+        return scheduled_operations
+
+    @_dispatcher_cache
+    def available_machines(self) -> list[int]:
+        """Returns the list of available machines."""
+        available_operations = self.available_operations()
+        available_machines = set()
+        for operation in available_operations:
+            available_machines.update(operation.machines)
+        return list(available_machines)
+
+    @_dispatcher_cache
+    def available_jobs(self) -> list[int]:
+        """Returns the list of available jobs."""
+        available_operations = self.available_operations()
+        available_jobs = set(
+            operation.job_id for operation in available_operations
+        )
+        return list(available_jobs)
+
+    def earliest_start_time(self, operation: Operation) -> int:
+        """Calculates the earliest start time for a given operation based on
+        machine and job constraints.
+
+        This method is different from the `start_time` method in that it
+        takes into account every machine that can process the operation, not
+        just the one that will process it. However, it also assumes that
+        the operation is ready to be scheduled in the job in favor of
+        performance.
+
+        Args:
+            operation:
+                The operation for which to calculate the earliest start time.
+
+        Returns:
+            The earliest start time for the operation.
+        """
+        machine_earliest_start_time = min(
+            self._machine_next_available_time[machine_id]
+            for machine_id in operation.machines
+        )
+        job_start_time = self._job_next_available_time[operation.job_id]
+        return max(machine_earliest_start_time, job_start_time)
+
+    def remaining_duration(
+        self, scheduled_operation: ScheduledOperation
+    ) -> int:
+        """Calculates the remaining duration of a scheduled operation.
+
+        The method computes the remaining time for an operation to finish,
+        based on the maximum of the operation's start time or the current time.
+        This helps in determining how much time is left from 'now' until the
+        operation is completed.
+
+        Args:
+            scheduled_operation:
+                The operation for which to calculate the remaining time.
+
+        Returns:
+            The remaining duration.
+        """
+        adjusted_start_time = max(
+            scheduled_operation.start_time, self.current_time()
+        )
+        return scheduled_operation.end_time - adjusted_start_time
+
+    @_dispatcher_cache
+    def completed_operations(self) -> set[Operation]:
+        """Returns the set of operations that have been completed.
+
+        This method returns the operations that have been scheduled and the
+        current time is greater than or equal to the end time of the operation.
+        """
+        scheduled_operations = set(self.scheduled_operations())
+        ongoing_operations = set(
+            map(
+                lambda scheduled_op: scheduled_op.operation,
+                self.ongoing_operations(),
+            )
+        )
+        completed_operations = scheduled_operations - ongoing_operations
+        return completed_operations
+
+    @_dispatcher_cache
+    def uncompleted_operations(self) -> list[Operation]:
+        """Returns the list of operations that have not been completed yet.
+
+        This method checks for operations that either haven't been scheduled
+        or have been scheduled but haven't reached their completion time.
+
+        Note:
+        The behavior of this method changed in version 0.5.0. Previously, it
+        only returned unscheduled operations. For the old behavior, use the
+        `unscheduled_operations` method.
+        """
+        uncompleted_operations = self.unscheduled_operations()
+        uncompleted_operations.extend(
+            scheduled_operation.operation
+            for scheduled_operation in self.ongoing_operations()
+        )
+        return uncompleted_operations
+
+    @_dispatcher_cache
+    def ongoing_operations(self) -> list[ScheduledOperation]:
+        """Returns the list of operations that are currently being processed.
+
+        This method returns the operations that have been scheduled and are
+        currently being processed by the machines.
+        """
+        current_time = self.current_time()
+        ongoing_operations = []
+        for machine_schedule in self.schedule.schedule:
+            for scheduled_operation in reversed(machine_schedule):
+                is_completed = scheduled_operation.end_time <= current_time
+                if is_completed:
+                    break
+                ongoing_operations.append(scheduled_operation)
+        return ongoing_operations
+
+    def is_scheduled(self, operation: Operation) -> bool:
+        """Checks if the given operation has been scheduled."""
+        job_next_op_idx = self._job_next_operation_index[operation.job_id]
+        return operation.position_in_job < job_next_op_idx
+
+    def is_ongoing(self, scheduled_operation: ScheduledOperation) -> bool:
+        """Checks if the given operation is currently being processed."""
+        current_time = self.current_time()
+        return scheduled_operation.start_time <= current_time
+
+    @classmethod
+    def create_schedule_from_raw_solution(
+        cls, instance: JobShopInstance, raw_solution: list[list[Operation]]
+    ) -> Schedule:
+        """Deprecated method, use `Schedule.from_job_sequences` instead."""
+        warn(
+            "Dispatcher.create_schedule_from_raw_solution is deprecated. "
+            "Use Schedule.from_job_sequences instead. It will be removed in "
+            "version 1.0.0.",
+            DeprecationWarning,
+        )
+        dispatcher = cls(instance)
+        dispatcher.reset()
+        raw_solution_deques = [
+            deque(operations) for operations in raw_solution
+        ]
+        while not dispatcher.schedule.is_complete():
+            for machine_id, operations in enumerate(raw_solution_deques):
+                if not operations:
+                    continue
+                operation = operations[0]
+                if dispatcher.is_operation_ready(operation):
+                    dispatcher.dispatch(operation, machine_id)
+                    operations.popleft()
+        return dispatcher.schedule

job_shop_lib-0.5.1/job_shop_lib/dispatching/feature_observers/__init__.py

@@ -0,0 +1,28 @@
+"""Contains FeatureObserver classes for observing features of the
+dispatcher."""
+
+from .feature_observer import FeatureObserver, FeatureType
+from .composite_feature_observer import CompositeFeatureObserver
+from .earliest_start_time_observer import EarliestStartTimeObserver
+from .is_ready_observer import IsReadyObserver
+from .duration_observer import DurationObserver
+from .is_scheduled_observer import IsScheduledObserver
+from .position_in_job_observer import PositionInJobObserver
+from .remaining_operations_observer import RemainingOperationsObserver
+from .is_completed_observer import IsCompletedObserver
+from .factory import FeatureObserverType, feature_observer_factory
+
+__all__ = [
+    "FeatureObserver",
+    "FeatureType",
+    "CompositeFeatureObserver",
+    "EarliestStartTimeObserver",
+    "IsReadyObserver",
+    "DurationObserver",
+    "IsScheduledObserver",
+    "PositionInJobObserver",
+    "RemainingOperationsObserver",
+    "IsCompletedObserver",
+    "FeatureObserverType",
+    "feature_observer_factory",
+]

job_shop_lib-0.5.1/job_shop_lib/dispatching/feature_observers/composite_feature_observer.py

@@ -0,0 +1,87 @@
+"""Home of the `CompositeFeatureObserver` class."""
+
+from collections import defaultdict
+import numpy as np
+import pandas as pd
+
+from job_shop_lib.dispatching import Dispatcher
+from job_shop_lib.dispatching.feature_observers import (
+    FeatureObserver,
+    FeatureType,
+)
+
+
+class CompositeFeatureObserver(FeatureObserver):
+    """Aggregates features from other FeatureObserver instances subscribed to
+    the same `Dispatcher` by concatenating their feature matrices along the
+    first axis (horizontal concatenation).
+
+    Attributes:
+        feature_observers:
+            List of `FeatureObserver` instances to aggregate features from.
+        column_names:
+            Dictionary mapping `FeatureType` to a list of column names for the
+            corresponding feature matrix. Column names are generated based on
+            the class name of the `FeatureObserver` instance that produced the
+            feature.
+    """
+
+    def __init__(
+        self,
+        dispatcher: Dispatcher,
+        feature_observers: list[FeatureObserver] | None = None,
+        subscribe: bool = True,
+    ):
+        if feature_observers is None:
+            feature_observers = [
+                observer
+                for observer in dispatcher.subscribers
+                if isinstance(observer, FeatureObserver)
+            ]
+        self.feature_observers = feature_observers
+        self.column_names: dict[FeatureType, list[str]] = defaultdict(list)
+        super().__init__(dispatcher, subscribe=subscribe)
+        self._set_column_names()
+
+    @property
+    def features_as_dataframe(self) -> dict[FeatureType, pd.DataFrame]:
+        """Returns the features as a dictionary of `pd.DataFrame` instances."""
+        return {
+            feature_type: pd.DataFrame(
+                feature_matrix, columns=self.column_names[feature_type]
+            )
+            for feature_type, feature_matrix in self.features.items()
+        }
+
+    def initialize_features(self):
+        features: dict[FeatureType, list[np.ndarray]] = defaultdict(list)
+        for observer in self.feature_observers:
+            for feature_type, feature_matrix in observer.features.items():
+                features[feature_type].append(feature_matrix)
+
+        self.features = {
+            feature_type: np.concatenate(features, axis=1)
+            for feature_type, features in features.items()
+        }
+
+    def _set_column_names(self):
+        for observer in self.feature_observers:
+            for feature_type, feature_matrix in observer.features.items():
+                feature_name = observer.__class__.__name__.replace(
+                    "Observer", ""
+                )
+                if feature_matrix.shape[1] > 1:
+                    self.column_names[feature_type] += [
+                        f"{feature_name}_{i}"
+                        for i in range(feature_matrix.shape[1])
+                    ]
+                else:
+                    self.column_names[feature_type].append(feature_name)
+
+    def __str__(self):
+        out = [f"{self.__class__.__name__}:"]
+        out.append("-" * (len(out[0]) - 1))
+        for feature_type, dataframe in self.features_as_dataframe.items():
+            out.append(f"{feature_type.value}:")
+            out.append(dataframe.to_string())
+        return "\n".join(out)

job_shop_lib-0.5.1/job_shop_lib/dispatching/feature_observers/duration_observer.py

@@ -0,0 +1,95 @@
+"""Home of the `DurationObserver` class."""
+
+import numpy as np
+
+from job_shop_lib.dispatching import Dispatcher
+from job_shop_lib import ScheduledOperation
+from job_shop_lib.dispatching.feature_observers import (
+    FeatureObserver,
+    FeatureType,
+)
+
+
+class DurationObserver(FeatureObserver):
+    """Measures the remaining duration of operations, machines, and jobs.
+
+    The duration of an Operation is:
+        - if the operation has not been scheduled, it is the duration of the
+        operation.
+        - if the operation has been scheduled, it is the remaining duration of
+        the operation.
+        - if the operation has been completed, it is the last duration of the
+        operation that has been computed. The duration must be set to 0
+        manually if needed. We do not update the duration of completed
+        operations to save computation time.
+
+    The duration of a Machine or Job is the sum of the durations of the
+    unscheduled operations that belong to the machine or job.
+    """
+
+    def __init__(
+        self,
+        dispatcher: Dispatcher,
+        feature_types: list[FeatureType] | FeatureType | None = None,
+        subscribe: bool = True,
+    ):
+        super().__init__(
+            dispatcher, feature_types, feature_size=1, subscribe=subscribe
+        )
+
+    def initialize_features(self):
+        mapping = {
+            FeatureType.OPERATIONS: self._initialize_operation_durations,
+            FeatureType.MACHINES: self._initialize_machine_durations,
+            FeatureType.JOBS: self._initialize_job_durations,
+        }
+        for feature_type in self.features:
+            mapping[feature_type]()
+
+    def update(self, scheduled_operation: ScheduledOperation):
+        mapping = {
+            FeatureType.OPERATIONS: self._update_operation_durations,
+            FeatureType.MACHINES: self._update_machine_durations,
+            FeatureType.JOBS: self._update_job_durations,
+        }
+        for feature_type in self.features:
+            mapping[feature_type](scheduled_operation)
+
+    def _initialize_operation_durations(self):
+        duration_matrix = self.dispatcher.instance.durations_matrix_array
+        operation_durations = np.array(duration_matrix).reshape(-1, 1)
+        # Drop the NaN values
+        operation_durations = operation_durations[
+            ~np.isnan(operation_durations)
+        ].reshape(-1, 1)
+        self.features[FeatureType.OPERATIONS] = operation_durations
+
+    def _initialize_machine_durations(self):
+        machine_durations = self.dispatcher.instance.machine_loads
+        for machine_id, machine_load in enumerate(machine_durations):
+            self.features[FeatureType.MACHINES][machine_id, 0] = machine_load
+
+    def _initialize_job_durations(self):
+        job_durations = self.dispatcher.instance.job_durations
+        for job_id, job_duration in enumerate(job_durations):
+            self.features[FeatureType.JOBS][job_id, 0] = job_duration
+
+    def _update_operation_durations(
+        self, scheduled_operation: ScheduledOperation
+    ):
+        operation_id = scheduled_operation.operation.operation_id
+        self.features[FeatureType.OPERATIONS][operation_id, 0] = (
+            self.dispatcher.remaining_duration(scheduled_operation)
+        )
+
+    def _update_machine_durations(
+        self, scheduled_operation: ScheduledOperation
+    ):
+        machine_id = scheduled_operation.machine_id
+        op_duration = scheduled_operation.operation.duration
+        self.features[FeatureType.MACHINES][machine_id, 0] -= op_duration
+
+    def _update_job_durations(self, scheduled_operation: ScheduledOperation):
+        operation_duration = scheduled_operation.operation.duration
+        job_id = scheduled_operation.job_id
+        self.features[FeatureType.JOBS][job_id, 0] -= operation_duration