job-shop-lib 0.5.1__py3-none-any.whl → 1.0.0a1__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
 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,74 @@ 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.
+
+    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.
+        """Initializes the observer with the :class:`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.
+            dispatcher:
+                The `Dispatcher` instance to observe.
             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 True, automatically subscribes the observer to the
+                dispatcher.
+
+        Raises:
+            ValidationError: If ``is_singleton`` is True and an observer of the
+                same type already exists in the dispatcher's list of
+                subscribers.
         """
-        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 +91,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 +115,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.
 
@@ -115,7 +161,7 @@ class Dispatcher:
             The instance of the job shop problem to be scheduled.
         schedule:
             The schedule of operations on machines.
-        pruning_function:
+        ready_operations_filter:
             A function that filters out operations that are not ready to be
             scheduled.
     """
@@ -126,7 +172,7 @@ class Dispatcher:
         "_machine_next_available_time",
         "_job_next_operation_index",
         "_job_next_available_time",
-        "pruning_function",
+        "ready_operations_filter",
         "subscribers",
         "_cache",
     )
@@ -134,7 +180,7 @@ class Dispatcher:
     def __init__(
         self,
         instance: JobShopInstance,
-        pruning_function: (
+        ready_operations_filter: (
             Callable[[Dispatcher, list[Operation]], list[Operation]] | None
         ) = None,
     ) -> None:
@@ -143,16 +189,17 @@ class Dispatcher:
         Args:
             instance:
                 The instance of the job shop problem to be solved.
-            pruning_function:
+            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 pruning is done.
+                that are ready to be scheduled. If ``None``, no filtering is
+                done.
         """
 
         self.instance = instance
         self.schedule = Schedule(self.instance)
-        self.pruning_function = pruning_function
+        self.ready_operations_filter = ready_operations_filter
 
         self._machine_next_available_time = [0] * self.instance.num_machines
         self._job_next_operation_index = [0] * self.instance.num_jobs
@@ -207,6 +254,7 @@ class Dispatcher:
         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.
@@ -215,11 +263,11 @@ class Dispatcher:
                 scheduled.
 
         Raises:
-            ValueError: If the operation is not ready to be scheduled.
+            ValidationError: If the operation is not ready to be scheduled.
         """
 
         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.")
 
         start_time = self.start_time(operation, machine_id)
 
@@ -229,10 +277,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,7 +309,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
+                scheduled. If ``None``, the start time is computed based on the
                 next available time for the operation on any machine.
         """
         return max(
@@ -286,6 +330,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.
@@ -293,7 +371,7 @@ class Dispatcher:
         The current time is the minimum start time of the available
         operations.
         """
-        available_operations = self.available_operations()
+        available_operations = self.ready_operations()
         current_time = self.min_start_time(available_operations)
         return current_time
 
@@ -309,39 +387,39 @@ class Dispatcher:
         return int(min_start_time)
 
     @_dispatcher_cache
-    def available_operations(self) -> list[Operation]:
+    def ready_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
@@ -364,8 +442,8 @@ class Dispatcher:
 
     @_dispatcher_cache
     def available_machines(self) -> list[int]:
-        """Returns the list of available machines."""
-        available_operations = self.available_operations()
+        """Returns the list of ready machines."""
+        available_operations = self.ready_operations()
         available_machines = set()
         for operation in available_operations:
             available_machines.update(operation.machines)
@@ -373,8 +451,8 @@ class Dispatcher:
 
     @_dispatcher_cache
     def available_jobs(self) -> list[int]:
-        """Returns the list of available jobs."""
-        available_operations = self.available_operations()
+        """Returns the list of ready jobs."""
+        available_operations = self.ready_operations()
         available_jobs = set(
             operation.job_id for operation in available_operations
         )
@@ -384,7 +462,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
@@ -489,28 +567,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,54 @@
+"""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
+
+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(slots=True, 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.
+
+    Attributes:
+        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
+            DispatcherObserver instances from the factory functions.
+        kwargs:
+            Keyword arguments needed to initialize the class. It must not
+            contain the ``dispatcher`` argument.
+    """
+
+    # 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
+    kwargs: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self):
+        if "dispatcher" in self.kwargs:
+            raise ValidationError(
+                "The 'dispatcher' argument should not be included in the "
+                "kwargs attribute."
+            )

job_shop_lib/dispatching/_factories.py

@@ -0,0 +1,125 @@
+"""Contains factory functions for creating ready operations filters.
+
+The factory functions create and return the appropriate functions based on the
+specified names or enums.
+"""
+
+from enum import Enum
+from collections.abc import Iterable
+
+from job_shop_lib import Operation
+from job_shop_lib.exceptions import ValidationError
+from job_shop_lib.dispatching import (
+    Dispatcher,
+    filter_dominated_operations,
+    filter_non_immediate_machines,
+    ReadyOperationsFilter,
+)
+
+
+class ReadyOperationsFilterType(str, Enum):
+    """Enumeration of ready operations filter types.
+
+    A filter function is used by the
+    :class:`~job_shop_lib.dispatching.Dispatcher` class to reduce the
+    amount of available operations to choose from.
+    """
+
+    DOMINATED_OPERATIONS = "dominated_operations"
+    NON_IMMEDIATE_MACHINES = "non_immediate_machines"
+
+
+def create_composite_operation_filter(
+    ready_operations_filters: Iterable[
+        ReadyOperationsFilter | str | ReadyOperationsFilterType
+    ],
+) -> ReadyOperationsFilter:
+    """Creates and returns a composite filter based on the specified list of
+    filters.
+
+    The composite filter function filters operations based on the specified
+    list of filter strategies.
+
+    Args:
+        ready_operations_filters:
+            A list of filter strategies to be used.
+            Supported values are 'dominated_operations' and
+            'non_immediate_machines' or any Callable that takes a
+            :class:`~job_shop_lib.dispatching.Dispatcher` instance and a list
+            of :class:`~job_shop_lib.Operation` instances as input
+            and returns a list of :class:`~job_shop_lib.Operation`instances.
+
+    Returns:
+        A function that takes a :class:`~job_shop_lib.dispatching.Dispatcher`
+        instance and a list of :class:`~job_shop_lib.Operation`
+        instances as input and returns a list of
+        :class:`~job_shop_lib.Operation`instances based on
+        the specified list of filter strategies.
+
+    Raises:
+        ValidationError: If any of the filter strategies in the list are not
+            recognized or are not supported.
+    """
+
+    filter_functions = [
+        ready_operations_filter_factory(name)
+        for name in ready_operations_filters
+    ]
+
+    def composite_pruning_function(
+        dispatcher: Dispatcher, operations: list[Operation]
+    ) -> list[Operation]:
+        pruned_operations = operations
+        for pruning_function in filter_functions:
+            pruned_operations = pruning_function(dispatcher, pruned_operations)
+
+        return pruned_operations
+
+    return composite_pruning_function
+
+
+def ready_operations_filter_factory(
+    filter_name: str | ReadyOperationsFilterType | ReadyOperationsFilter,
+) -> ReadyOperationsFilter:
+    """Creates and returns a filter function based on the specified
+    filter strategy name.
+
+    The filter function filters operations based on certain criteria such as
+    dominated operations, immediate machine operations, etc.
+
+    Args:
+        filter_name:
+            The name of the filter function to be used. Supported
+            values are 'dominated_operations' and
+            'immediate_machine_operations'.
+
+    Returns:
+        A function that takes a :class:`~job_shop_lib.dispatching.Dispatcher`
+        instance and a list of :class:`~job_shop_lib.Operation`
+        instances as input and returns a list of
+        :class:`~job_shop_lib.Operation` instances based on
+        the specified filter function.
+
+    Raises:
+        ValidationError: If the ``filter_name`` argument is not recognized or
+            is not supported.
+    """
+    if callable(filter_name):
+        return filter_name
+
+    filtering_strategies = {
+        ReadyOperationsFilterType.DOMINATED_OPERATIONS: (
+            filter_dominated_operations
+        ),
+        ReadyOperationsFilterType.NON_IMMEDIATE_MACHINES: (
+            filter_non_immediate_machines
+        ),
+    }
+
+    if filter_name not in filtering_strategies:
+        raise ValidationError(
+            f"Unsupported filter function '{filter_name}'. "
+            f"Supported values are {', '.join(filtering_strategies.keys())}."
+        )
+
+    return filtering_strategies[filter_name]  # type: ignore[index]

job_shop_lib/dispatching/{history_tracker.py → _history_observer.py}

@@ -1,16 +1,14 @@
-"""Home of the `HistoryTracker` class."""
+"""Home of the `HistoryObserver` class."""
 
 from job_shop_lib.dispatching import DispatcherObserver, Dispatcher
 from job_shop_lib import ScheduledOperation
 
 
-class HistoryTracker(DispatcherObserver):
+class HistoryObserver(DispatcherObserver):
     """Observer that stores the history of the dispatcher."""
 
-    def __init__(self, dispatcher: Dispatcher):
-        """Initializes the observer with the current state of the
-        dispatcher."""
-        super().__init__(dispatcher)
+    def __init__(self, dispatcher: Dispatcher, *, subscribe: bool = True):
+        super().__init__(dispatcher, subscribe=subscribe)
         self.history: list[ScheduledOperation] = []
 
     def update(self, scheduled_operation: ScheduledOperation):

job_shop_lib/dispatching/{pruning_functions.py → _ready_operation_filters.py}

@@ -4,47 +4,18 @@ This functions are used by the `Dispatcher` class to reduce the
 amount of available operations to choose from.
 """
 
-from collections.abc import Callable, Iterable
+from collections.abc import Callable
 
 from job_shop_lib import Operation
 from job_shop_lib.dispatching import Dispatcher
 
 
-def create_composite_pruning_function(
-    pruning_functions: Iterable[
-        Callable[[Dispatcher, list[Operation]], list[Operation]]
-    ],
-) -> Callable[[Dispatcher, list[Operation]], list[Operation]]:
-    """Creates and returns a composite pruning strategy function based on the
-    specified list of pruning strategies.
-    The composite pruning strategy function filters out operations based on
-    the specified list of pruning strategies.
-    Args:
-        pruning_strategies:
-            A list of pruning strategies to be used. Supported values are
-            'dominated_operations' and 'non_immediate_machines'.
-    Returns:
-        A function that takes a Dispatcher instance and a list of Operation
-        instances as input and returns a list of Operation instances based on
-        the specified list of pruning strategies.
-    Raises:
-        ValueError: If any of the pruning strategies in the list are not
-            recognized or are not supported.
-    """
-
-    def composite_pruning_function(
-        dispatcher: Dispatcher, operations: list[Operation]
-    ) -> list[Operation]:
-        pruned_operations = operations
-        for pruning_function in pruning_functions:
-            pruned_operations = pruning_function(dispatcher, pruned_operations)
-
-        return pruned_operations
-
-    return composite_pruning_function
+ReadyOperationsFilter = Callable[
+    [Dispatcher, list[Operation]], list[Operation]
+]
 
 
-def prune_dominated_operations(
+def filter_dominated_operations(
     dispatcher: Dispatcher, operations: list[Operation]
 ) -> list[Operation]:
     """Filters out all the operations that are dominated.
@@ -69,7 +40,7 @@ def prune_dominated_operations(
     return non_dominated_operations
 
 
-def prune_non_immediate_machines(
+def filter_non_immediate_machines(
     dispatcher: Dispatcher, operations: list[Operation]
 ) -> list[Operation]:
     """Filters out all the operations associated with machines which earliest