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

job_shop_lib/dispatching/{dispatcher.py → _dispatcher.py}

@@ -3,11 +3,9 @@
 from __future__ import annotations
 
 import abc
-from typing import Any
+from typing import Any, TypeVar, List, Optional, Type, Set
 from collections.abc import Callable
-from collections import deque
 from functools import wraps
-from warnings import warn
 
 from job_shop_lib import (
     JobShopInstance,
@@ -15,40 +13,71 @@ from job_shop_lib import (
     ScheduledOperation,
     Operation,
 )
+from job_shop_lib.exceptions import ValidationError
 
 
 # Added here to avoid circular imports
 class DispatcherObserver(abc.ABC):
-    """Interface for classes that observe th"""
+    """Abstract class that allows objects to observe and respond to changes
+    within the :class:`Dispatcher`.
+
+    It follows the Observer design pattern, where observers subscribe to the
+    dispatcher and receive updates when certain events occur, such as when
+    an operation is scheduled or when the dispatcher is reset.
+
+    Attributes:
+        dispatcher:
+            The :class:`Dispatcher` instance to observe.
+
+    Args:
+        dispatcher:
+            The :class:`Dispatcher` instance to observe.
+        subscribe:
+            If ``True``, automatically subscribes the observer to the
+            dispatcher when it is initialized. Defaults to ``True``.
+
+    Raises:
+        ValidationError: If ``is_singleton`` is ``True`` and an observer of the
+            same type already exists in the dispatcher's list of
+            subscribers.
+
+    Example:
+
+    .. code-block:: python
+
+        from job_shop_lib.dispatching import DispatcherObserver, Dispatcher
+        from job_shop_lib import ScheduledOperation
+
+
+        class HistoryObserver(DispatcherObserver):
+            def __init__(self, dispatcher: Dispatcher):
+                super().__init__(dispatcher)
+                self.history: List[ScheduledOperation] = []
+
+            def update(self, scheduled_operation: ScheduledOperation):
+                self.history.append(scheduled_operation)
+
+            def reset(self):
+                self.history = []
+
+    """
+
+    # Made read-only following Google Style Guide recommendation
+    _is_singleton = True
+    """If True, ensures only one instance of this observer type is subscribed
+    to the dispatcher."""
 
     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(
+        if self._is_singleton and any(
             isinstance(observer, self.__class__)
             for observer in dispatcher.subscribers
         ):
-            raise ValueError(
+            raise ValidationError(
                 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 "
@@ -59,6 +88,15 @@ class DispatcherObserver(abc.ABC):
         if subscribe:
             self.dispatcher.subscribe(self)
 
+    @property
+    def is_singleton(self) -> bool:
+        """Returns whether this observer is a singleton.
+
+        This is a class attribute that determines whether only one
+        instance of this observer type can be subscribed to the dispatcher.
+        """
+        return self._is_singleton
+
     @abc.abstractmethod
     def update(self, scheduled_operation: ScheduledOperation):
         """Called when an operation is scheduled on a machine."""
@@ -74,6 +112,11 @@ class DispatcherObserver(abc.ABC):
         return self.__class__.__name__
 
 
+# Disable pylint's false positive
+# pylint: disable=invalid-name
+ObserverType = TypeVar("ObserverType", bound=DispatcherObserver)
+
+
 def _dispatcher_cache(method):
     """Decorator to cache results of a method based on its name.
 
@@ -110,54 +153,77 @@ class Dispatcher:
     responsible for scheduling the operations on the machines and keeping
     track of the next available time for each machine and job.
 
-    Attributes:
+    The core method of the class are:
+
+    .. autosummary::
+
+        dispatch
+        reset
+
+    It also provides methods to query the state of the schedule and the
+    operations:
+
+    .. autosummary::
+
+        current_time
+        available_operations
+        available_machines
+        available_jobs
+        unscheduled_operations
+        scheduled_operations
+        ongoing_operations
+        completed_operations
+        uncompleted_operations
+        is_scheduled
+        is_ongoing
+        next_operation
+        earliest_start_time
+        remaining_duration
+
+    The above methods which do not take any arguments are cached to improve
+    performance. After each scheduling operation, the cache is cleared.
+
+    Args:
         instance:
-            The instance of the job shop problem to be scheduled.
-        schedule:
-            The schedule of operations on machines.
-        pruning_function:
-            A function that filters out operations that are not ready to be
-            scheduled.
+            The instance of the job shop problem to be solved.
+        ready_operations_filter:
+            A function that filters out operations that are not ready to
+            be scheduled. The function should take the dispatcher and a
+            list of operations as input and return a list of operations
+            that are ready to be scheduled. If ``None``, no filtering is
+            done.
     """
 
-    __slots__ = (
-        "instance",
-        "schedule",
-        "_machine_next_available_time",
-        "_job_next_operation_index",
-        "_job_next_available_time",
-        "pruning_function",
-        "subscribers",
-        "_cache",
-    )
+    __slots__ = {
+        "instance": "The instance of the job shop problem to be scheduled.",
+        "schedule": "The schedule of operations on machines.",
+        "_machine_next_available_time": "",
+        "_job_next_operation_index": "",
+        "_job_next_available_time": "",
+        "ready_operations_filter": (
+            "A function that filters out operations that are not ready to be "
+            "scheduled."
+        ),
+        "subscribers": "A list of observers subscribed to the dispatcher.",
+        "_cache": "A dictionary to cache the results of the cached methods.",
+    }
 
     def __init__(
         self,
         instance: JobShopInstance,
-        pruning_function: (
-            Callable[[Dispatcher, list[Operation]], list[Operation]] | None
+        ready_operations_filter: (
+            Optional[Callable[[Dispatcher, List[Operation]], List[Operation]]]
         ) = None,
     ) -> None:
-        """Initializes the object with the given instance.
-
-        Args:
-            instance:
-                The instance of the job shop problem to be solved.
-            pruning_function:
-                A function that filters out operations that are not ready to
-                be scheduled. The function should take the dispatcher and a
-                list of operations as input and return a list of operations
-                that are ready to be scheduled. If `None`, no pruning is done.
-        """
 
         self.instance = instance
         self.schedule = Schedule(self.instance)
-        self.pruning_function = pruning_function
+        self.ready_operations_filter = ready_operations_filter
+        self.subscribers: List[DispatcherObserver] = []
 
         self._machine_next_available_time = [0] * self.instance.num_machines
         self._job_next_operation_index = [0] * self.instance.num_jobs
         self._job_next_available_time = [0] * self.instance.num_jobs
-        self.subscribers: list[DispatcherObserver] = []
         self._cache: dict[str, Any] = {}
 
     def __str__(self) -> str:
@@ -167,18 +233,18 @@ class Dispatcher:
         return str(self)
 
     @property
-    def machine_next_available_time(self) -> list[int]:
+    def machine_next_available_time(self) -> List[int]:
         """Returns the next available time for each machine."""
         return self._machine_next_available_time
 
     @property
-    def job_next_operation_index(self) -> list[int]:
+    def job_next_operation_index(self) -> List[int]:
         """Returns the index of the next operation to be scheduled for each
         job."""
         return self._job_next_operation_index
 
     @property
-    def job_next_available_time(self) -> list[int]:
+    def job_next_available_time(self) -> List[int]:
         """Returns the next available time for each job."""
         return self._job_next_available_time
 
@@ -200,26 +266,35 @@ class Dispatcher:
         for subscriber in self.subscribers:
             subscriber.reset()
 
-    def dispatch(self, operation: Operation, machine_id: int) -> None:
+    def dispatch(
+        self, operation: Operation, machine_id: Optional[int] = None
+    ) -> None:
         """Schedules the given operation on the given machine.
 
         The start time of the operation is computed based on the next
         available time for the machine and the next available time for the
         job to which the operation belongs. The operation is then scheduled
         on the machine and the tracking attributes are updated.
+
         Args:
             operation:
                 The operation to be scheduled.
             machine_id:
                 The id of the machine on which the operation is to be
-                scheduled.
+                scheduled. If ``None``, the :class:`~job_shop_lib.Operation`'s
+                :attr:`~job_shop_lib.Operation.machine_id` attribute is used.
 
         Raises:
-            ValueError: If the operation is not ready to be scheduled.
+            ValidationError: If the operation is not ready to be scheduled.
+            UninitializedAttributeError: If the operation has multiple
+                machines in its list and no ``machine_id`` is provided.
         """
 
         if not self.is_operation_ready(operation):
-            raise ValueError("Operation is not ready to be scheduled.")
+            raise ValidationError("Operation is not ready to be scheduled.")
+
+        if machine_id is None:
+            machine_id = operation.machine_id
 
         start_time = self.start_time(operation, machine_id)
 
@@ -229,10 +304,6 @@ class Dispatcher:
         self.schedule.add(scheduled_operation)
         self._update_tracking_attributes(scheduled_operation)
 
-        # Notify subscribers
-        for subscriber in self.subscribers:
-            subscriber.update(scheduled_operation)
-
     def is_operation_ready(self, operation: Operation) -> bool:
         """Returns True if the given operation is ready to be scheduled.
 
@@ -265,8 +336,7 @@ class Dispatcher:
                 The operation to be scheduled.
             machine_id:
                 The id of the machine on which the operation is to be
-                scheduled. If None, the start time is computed based on the
-                next available time for the operation on any machine.
+                scheduled.
         """
         return max(
             self._machine_next_available_time[machine_id],
@@ -286,6 +356,40 @@ class Dispatcher:
         self._job_next_available_time[job_id] = end_time
         self._cache = {}
 
+        # Notify subscribers
+        for subscriber in self.subscribers:
+            subscriber.update(scheduled_operation)
+
+    def create_or_get_observer(
+        self,
+        observer: Type[ObserverType],
+        condition: Callable[[DispatcherObserver], bool] = lambda _: True,
+        **kwargs,
+    ) -> ObserverType:
+        """Creates a new observer of the specified type or returns an existing
+        observer of the same type if it already exists in the dispatcher's list
+        of observers.
+
+        Args:
+            observer:
+                The type of observer to be created or retrieved.
+            condition:
+                A function that takes an observer and returns True if it is
+                the observer to be retrieved. By default, it returns True for
+                all observers.
+            **kwargs:
+                Additional keyword arguments to be passed to the observer's
+                constructor.
+        """
+        for existing_observer in self.subscribers:
+            if isinstance(existing_observer, observer) and condition(
+                existing_observer
+            ):
+                return existing_observer
+
+        new_observer = observer(self, **kwargs)
+        return new_observer
+
     @_dispatcher_cache
     def current_time(self) -> int:
         """Returns the current time of the schedule.
@@ -297,7 +401,7 @@ class Dispatcher:
         current_time = self.min_start_time(available_operations)
         return current_time
 
-    def min_start_time(self, operations: list[Operation]) -> int:
+    def min_start_time(self, operations: List[Operation]) -> int:
         """Returns the minimum start time of the available operations."""
         if not operations:
             return self.schedule.makespan()
@@ -309,43 +413,43 @@ class Dispatcher:
         return int(min_start_time)
 
     @_dispatcher_cache
-    def available_operations(self) -> list[Operation]:
+    def available_operations(self) -> List[Operation]:
         """Returns a list of available operations for processing, optionally
-        filtering out operations using the pruning function.
+        filtering out operations using the filter function.
 
         This method first gathers all possible next operations from the jobs
         being processed. It then optionally filters these operations using the
-        pruning function.
+        filter function.
 
         Returns:
-            A list of Operation objects that are available for scheduling.
+            A list of :class:`Operation` objects that are available for
+            scheduling.
         """
-        available_operations = self.available_operations_without_pruning()
-        if self.pruning_function is not None:
-            available_operations = self.pruning_function(
+        available_operations = self.raw_ready_operations()
+        if self.ready_operations_filter is not None:
+            available_operations = self.ready_operations_filter(
                 self, available_operations
             )
         return available_operations
 
     @_dispatcher_cache
-    def available_operations_without_pruning(self) -> list[Operation]:
+    def raw_ready_operations(self) -> List[Operation]:
         """Returns a list of available operations for processing without
-        applying the pruning function.
+        applying the filter function.
 
         Returns:
-            A list of Operation objects that are available for scheduling
-            based on precedence and machine constraints only.
+            A list of :class:`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]):
-                continue
-            operation = self.instance.jobs[job_id][next_position]
-            available_operations.append(operation)
+        available_operations = [
+            self.instance.jobs[job_id][position]
+            for job_id, position in enumerate(self._job_next_operation_index)
+            if position < len(self.instance.jobs[job_id])
+        ]
         return available_operations
 
     @_dispatcher_cache
-    def unscheduled_operations(self) -> list[Operation]:
+    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):
@@ -354,17 +458,16 @@ class Dispatcher:
         return unscheduled_operations
 
     @_dispatcher_cache
-    def scheduled_operations(self) -> list[Operation]:
+    def scheduled_operations(self) -> List[ScheduledOperation]:
         """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)
+        for machine_schedule in self.schedule.schedule:
+            scheduled_operations.extend(machine_schedule)
         return scheduled_operations
 
     @_dispatcher_cache
-    def available_machines(self) -> list[int]:
-        """Returns the list of available machines."""
+    def available_machines(self) -> List[int]:
+        """Returns the list of ready machines."""
         available_operations = self.available_operations()
         available_machines = set()
         for operation in available_operations:
@@ -372,8 +475,8 @@ class Dispatcher:
         return list(available_machines)
 
     @_dispatcher_cache
-    def available_jobs(self) -> list[int]:
-        """Returns the list of available jobs."""
+    def available_jobs(self) -> List[int]:
+        """Returns the list of ready jobs."""
         available_operations = self.available_operations()
         available_jobs = set(
             operation.job_id for operation in available_operations
@@ -384,7 +487,7 @@ class Dispatcher:
         """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
+        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
@@ -427,24 +530,19 @@ class Dispatcher:
         return scheduled_operation.end_time - adjusted_start_time
 
     @_dispatcher_cache
-    def completed_operations(self) -> set[Operation]:
+    def completed_operations(self) -> Set[ScheduledOperation]:
         """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(),
-            )
-        )
+        ongoing_operations = set(self.ongoing_operations())
         completed_operations = scheduled_operations - ongoing_operations
         return completed_operations
 
     @_dispatcher_cache
-    def uncompleted_operations(self) -> list[Operation]:
+    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
@@ -463,7 +561,7 @@ class Dispatcher:
         return uncompleted_operations
 
     @_dispatcher_cache
-    def ongoing_operations(self) -> list[ScheduledOperation]:
+    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
@@ -489,28 +587,23 @@ class Dispatcher:
         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
+    def next_operation(self, job_id: int) -> Operation:
+        """Returns the next operation to be scheduled for the given job.
+
+        Args:
+            job_id:
+                The id of the job for which to return the next operation.
+
+        Raises:
+            ValidationError: If there are no more operations left for the job.
+        """
+        if (
+            len(self.instance.jobs[job_id])
+            <= self._job_next_operation_index[job_id]
+        ):
+            raise ValidationError(
+                f"No more operations left for job {job_id} to schedule."
+            )
+        return self.instance.jobs[job_id][
+            self._job_next_operation_index[job_id]
         ]
-        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/dispatching/_dispatcher_observer_config.py

@@ -0,0 +1,67 @@
+"""Contains factory functions for creating dispatching rules, machine choosers,
+and pruning functions for the job shop scheduling problem.
+
+The factory functions create and return the appropriate functions based on the
+specified names or enums.
+"""
+
+from typing import TypeVar, Generic, Any, Dict
+
+from dataclasses import dataclass, field
+
+from job_shop_lib.exceptions import ValidationError
+
+
+# Disable pylint's false positive
+# pylint: disable=invalid-name
+T = TypeVar("T")
+
+
+@dataclass(frozen=True)
+class DispatcherObserverConfig(Generic[T]):
+    """Configuration for initializing any type of class.
+
+    Useful for specifying the type of the
+    :class:`~job_shop_lib.dispatching.DispatcherObserver` and additional
+    keyword arguments to pass to the dispatcher observer constructor while
+    not containing the ``dispatcher`` argument.
+
+    Args:
+        class_type:
+            Type of the class to be initialized. It can be the class type, an
+            enum value, or a string. This is useful for the creation of
+            :class:`~job_shop_lib.dispatching.DispatcherObserver` instances
+            from the factory functions.
+        kwargs:
+            Keyword arguments needed to initialize the class. It must not
+            contain the ``dispatcher`` argument.
+
+    .. seealso::
+
+        - :class:`~job_shop_lib.dispatching.DispatcherObserver`
+        - :func:`job_shop_lib.dispatching.feature_observers.\\
+          feature_observer_factory`
+    """
+
+    # We use the type hint T, instead of ObserverType, to allow for string or
+    # specific Enum values to be passed as the type argument. For example:
+    # FeatureObserverConfig = DispatcherObserverConfig[
+    #     Type[FeatureObserver] | FeatureObserverType | str
+    # ]
+    # This allows for the creation of a FeatureObserver instance
+    # from the factory function.
+    class_type: T
+    """Type of the class to be initialized. It can be the class type, an
+    enum value, or a string. This is useful for the creation of
+    :class:`DispatcherObserver` instances from the factory functions."""
+
+    kwargs: Dict[str, Any] = field(default_factory=dict)
+    """Keyword arguments needed to initialize the class. It must not
+    contain the ``dispatcher`` argument."""
+
+    def __post_init__(self):
+        if "dispatcher" in self.kwargs:
+            raise ValidationError(
+                "The 'dispatcher' argument should not be included in the "
+                "kwargs attribute."
+            )