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

job_shop_lib/dispatching/_factories.py

@@ -0,0 +1,135 @@
+"""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 typing import Union
+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,
+    filter_non_idle_machines,
+    filter_non_immediate_operations,
+    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"
+    NON_IDLE_MACHINES = "non_idle_machines"
+    NON_IMMEDIATE_OPERATIONS = "non_immediate_operations"
+
+
+def create_composite_operation_filter(
+    ready_operations_filters: Iterable[
+        Union[ReadyOperationsFilter, str, ReadyOperationsFilterType]
+    ],
+) -> ReadyOperationsFilter:
+    """Creates and returns a :class:`ReadyOperationsFilter` function by
+    combining multiple filter strategies.
+
+    The composite filter function applies multiple filter strategies
+    iteratively in the order they are specified in the list.
+
+    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: Union[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. See
+            :class:`ReadyOperationsFilterType` for supported values.
+            Alternatively, a custom filter function can be passed directly.
+
+    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
+        ),
+        ReadyOperationsFilterType.NON_IDLE_MACHINES: filter_non_idle_machines,
+        ReadyOperationsFilterType.NON_IMMEDIATE_OPERATIONS: (
+            filter_non_immediate_operations
+        ),
+    }
+
+    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,17 +1,16 @@
-"""Home of the `HistoryTracker` class."""
+"""Home of the `HistoryObserver` class."""
 
+from typing import List
 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)
-        self.history: list[ScheduledOperation] = []
+    def __init__(self, dispatcher: Dispatcher, *, subscribe: bool = True):
+        super().__init__(dispatcher, subscribe=subscribe)
+        self.history: List[ScheduledOperation] = []
 
     def update(self, scheduled_operation: ScheduledOperation):
         self.history.append(scheduled_operation)

job_shop_lib/dispatching/_optimal_operations_observer.py

@@ -0,0 +1,113 @@
+"""Home of the `OptimalOperationsObserver` class."""
+
+from typing import List, Set, Dict
+from job_shop_lib.dispatching import DispatcherObserver, Dispatcher
+from job_shop_lib import Schedule, Operation, ScheduledOperation
+from job_shop_lib.exceptions import ValidationError
+
+
+class OptimalOperationsObserver(DispatcherObserver):
+    """Observer that identifies which available operations are optimal based on
+    a reference schedule.
+
+    This observer compares the available operations at each step with a
+    reference schedule to determine which operations would lead to the optimal
+    solution. It can be used for training purposes or to analyze decision
+    making in dispatching algorithms.
+
+    Attributes:
+        optimal_operations: Set of operations that are considered optimal
+            based on the reference schedule.
+        reference_schedule: The reference schedule used to determine optimal
+            operations.
+
+    Args:
+        dispatcher: The dispatcher instance to observe.
+        reference_schedule: A complete schedule that represents the optimal
+            or reference solution.
+        subscribe: If True, automatically subscribes to the dispatcher.
+
+    Raises:
+        ValidationError: If the reference schedule is incomplete or if it
+            doesn't match the dispatcher's instance.
+    """
+
+    _is_singleton = False
+
+    def __init__(
+        self,
+        dispatcher: Dispatcher,
+        reference_schedule: Schedule,
+        *,
+        subscribe: bool = True,
+    ):
+        super().__init__(dispatcher, subscribe=subscribe)
+
+        if not reference_schedule.is_complete():
+            raise ValidationError("Reference schedule must be complete.")
+
+        if reference_schedule.instance != dispatcher.instance:
+            raise ValidationError(
+                "Reference schedule instance does not match dispatcher "
+                "instance."
+            )
+
+        self.reference_schedule = reference_schedule
+        self.optimal_available: Set[Operation] = set()
+        self._operation_to_scheduled: Dict[Operation, ScheduledOperation] = {}
+        self._machine_next_operation_index: List[int] = [0] * len(
+            reference_schedule.schedule
+        )
+
+        self._build_operation_mapping()
+        self._update_optimal_operations()
+
+    def _build_operation_mapping(self) -> None:
+        """Builds a mapping from operations to their scheduled versions in
+        the reference schedule."""
+        for machine_schedule in self.reference_schedule.schedule:
+            for scheduled_op in machine_schedule:
+                self._operation_to_scheduled[scheduled_op.operation] = (
+                    scheduled_op
+                )
+
+    def _update_optimal_operations(self) -> None:
+        """Updates the set of optimal operations based on current state.
+
+        An operation is considered optimal if it is the next unscheduled
+        operation in its machine's sequence according to the reference
+        schedule.
+        """
+        self.optimal_available.clear()
+        available_operations = self.dispatcher.available_operations()
+
+        if not available_operations:
+            return
+
+        for operation in available_operations:
+            scheduled_op = self._operation_to_scheduled[operation]
+            machine_index = scheduled_op.machine_id
+            next_index = self._machine_next_operation_index[machine_index]
+
+            if (
+                scheduled_op
+                == self.reference_schedule.schedule[machine_index][next_index]
+            ):
+                self.optimal_available.add(operation)
+
+    def update(self, scheduled_operation: ScheduledOperation) -> None:
+        """Updates the optimal operations after an operation is scheduled.
+
+        Args:
+            scheduled_operation: The operation that was just scheduled.
+        """
+        self._machine_next_operation_index[scheduled_operation.machine_id] += 1
+        self._update_optimal_operations()
+
+    def reset(self) -> None:
+        """Resets the observer to its initial state."""
+        self._machine_next_operation_index = [0] * len(
+            self.dispatcher.schedule.schedule
+        )
+        self.optimal_available.clear()
+        self._update_optimal_operations()

job_shop_lib/dispatching/_ready_operation_filters.py

@@ -0,0 +1,168 @@
+"""Contains functions to prune (filter) operations.
+
+This functions are used by the `Dispatcher` class to reduce the
+amount of available operations to choose from.
+"""
+
+from typing import List, Set
+from collections.abc import Callable
+
+from job_shop_lib import Operation
+from job_shop_lib.dispatching import Dispatcher
+
+
+ReadyOperationsFilter = Callable[
+    [Dispatcher, List[Operation]], List[Operation]
+]
+
+
+def filter_non_idle_machines(
+    dispatcher: Dispatcher, operations: List[Operation]
+) -> List[Operation]:
+    """Filters out all the operations associated with non-idle machines.
+
+    A machine is considered idle if there are no ongoing operations
+    currently scheduled on it. This filter removes operations that are
+    associated with machines that are busy (i.e., have at least one
+    uncompleted operation).
+
+    Utilizes :meth:``Dispatcher.ongoing_operations()`` to determine machine
+    statuses.
+
+    Args:
+        dispatcher: The dispatcher object.
+        operations: The list of operations to filter.
+
+    Returns:
+        The list of operations that are associated with idle machines.
+    """
+    current_time = dispatcher.min_start_time(operations)
+    non_idle_machines = _get_non_idle_machines(dispatcher, current_time)
+
+    # Filter operations to keep those that are associated with at least one
+    # idle machine
+    filtered_operations: List[Operation] = []
+    for operation in operations:
+        if all(
+            machine_id in non_idle_machines
+            for machine_id in operation.machines
+        ):
+            continue
+        filtered_operations.append(operation)
+
+    return filtered_operations
+
+
+def _get_non_idle_machines(
+    dispatcher: Dispatcher, current_time: int
+) -> Set[int]:
+    """Returns the set of machine ids that are currently busy (i.e., have at
+    least one uncompleted operation)."""
+
+    non_idle_machines = set()
+    for machine_schedule in dispatcher.schedule.schedule:
+        for scheduled_operation in reversed(machine_schedule):
+            is_completed = scheduled_operation.end_time <= current_time
+            if is_completed:
+                break
+            non_idle_machines.add(scheduled_operation.machine_id)
+
+    return non_idle_machines
+
+
+def filter_non_immediate_operations(
+    dispatcher: Dispatcher, operations: List[Operation]
+) -> List[Operation]:
+    """Filters out all the operations that can't start immediately.
+
+    An operation can start immediately if its earliest start time is the
+    current time.
+
+    The current time is determined by the minimum start time of the
+    operations.
+
+    Args:
+        dispatcher: The dispatcher object.
+        operations: The list of operations to filter.
+    """
+
+    min_start_time = dispatcher.min_start_time(operations)
+    immediate_operations: List[Operation] = []
+    for operation in operations:
+        start_time = dispatcher.earliest_start_time(operation)
+        if start_time == min_start_time:
+            immediate_operations.append(operation)
+
+    return immediate_operations
+
+
+def filter_dominated_operations(
+    dispatcher: Dispatcher, operations: List[Operation]
+) -> List[Operation]:
+    """Filters out all the operations that are dominated.
+    An operation is dominated if there is another operation that ends before
+    it starts on the same machine.
+    """
+
+    min_machine_end_times = _get_min_machine_end_times(dispatcher, operations)
+
+    non_dominated_operations: List[Operation] = []
+    for operation in operations:
+        # One benchmark instance has an operation with duration 0
+        if operation.duration == 0:
+            return [operation]
+        for machine_id in operation.machines:
+            start_time = dispatcher.start_time(operation, machine_id)
+            is_dominated = start_time >= min_machine_end_times[machine_id]
+            if not is_dominated:
+                non_dominated_operations.append(operation)
+                break
+
+    return non_dominated_operations
+
+
+def filter_non_immediate_machines(
+    dispatcher: Dispatcher, operations: List[Operation]
+) -> List[Operation]:
+    """Filters out all the operations associated with machines which earliest
+    operation is not the current time."""
+
+    is_immediate_machine = _get_immediate_machines(dispatcher, operations)
+    non_dominated_operations: List[Operation] = []
+    for operation in operations:
+        if any(
+            is_immediate_machine[machine_id]
+            for machine_id in operation.machines
+        ):
+            non_dominated_operations.append(operation)
+
+    return non_dominated_operations
+
+
+def _get_min_machine_end_times(
+    dispatcher: Dispatcher, available_operations: List[Operation]
+) -> List[float]:
+    end_times_per_machine = [float("inf")] * dispatcher.instance.num_machines
+    for op in available_operations:
+        for machine_id in op.machines:
+            start_time = dispatcher.start_time(op, machine_id)
+            end_times_per_machine[machine_id] = min(
+                end_times_per_machine[machine_id], start_time + op.duration
+            )
+    return end_times_per_machine
+
+
+def _get_immediate_machines(
+    dispatcher: Dispatcher, available_operations: List[Operation]
+) -> List[bool]:
+    """Returns the machine ids of the machines that have at least one
+    operation with the lowest start time (i.e. the start time)."""
+    working_machines = [False] * dispatcher.instance.num_machines
+    # We can't use the current_time directly because it will cause
+    # an infinite loop.
+    current_time = dispatcher.min_start_time(available_operations)
+    for op in available_operations:
+        for machine_id in op.machines:
+            if dispatcher.start_time(op, machine_id) == current_time:
+                working_machines[machine_id] = True
+    return working_machines

job_shop_lib/dispatching/_unscheduled_operations_observer.py

@@ -0,0 +1,70 @@
+"""Home of the `UnscheduledOperationsObserver` class."""
+
+import collections
+from collections.abc import Iterable
+import itertools
+from typing import Deque, List
+
+from job_shop_lib import Operation, ScheduledOperation
+from job_shop_lib.dispatching import DispatcherObserver, Dispatcher
+
+
+class UnscheduledOperationsObserver(DispatcherObserver):
+    """Stores the operations that have not been dispatched yet.
+
+    This observer maintains a list of deques, each containing unscheduled
+    operations for a specific job. It provides methods to access and
+    manipulate unscheduled operations efficiently.
+    """
+
+    def __init__(self, dispatcher: Dispatcher, *, subscribe: bool = True):
+        super().__init__(dispatcher, subscribe=subscribe)
+        self.unscheduled_operations_per_job: List[Deque[Operation]] = []
+        self.reset()
+        # In case the dispatcher has already scheduled some operations,
+        # we need to remove them.
+        # Note that we don't need to remove the operations in order.
+        for scheduled_operation in itertools.chain(
+            *self.dispatcher.schedule.schedule
+        ):
+            self.update(scheduled_operation)
+
+    @property
+    def unscheduled_operations(self) -> Iterable[Operation]:
+        """An iterable of all unscheduled operations across all jobs."""
+        return itertools.chain(*self.unscheduled_operations_per_job)
+
+    @property
+    def num_unscheduled_operations(self) -> int:
+        """The total number of unscheduled operations."""
+        total_operations = self.dispatcher.instance.num_operations
+        num_scheduled_operations = (
+            self.dispatcher.schedule.num_scheduled_operations
+        )
+        return total_operations - num_scheduled_operations
+
+    def update(self, scheduled_operation: ScheduledOperation) -> None:
+        """Removes a scheduled operation from the unscheduled operations.
+
+        This method is called by the dispatcher when an operation is
+        scheduled. It removes the operation from its job's deque of
+        unscheduled operations.
+
+        Args:
+            scheduled_operation:
+                The operation that has been scheduled.
+        """
+        job_id = scheduled_operation.operation.job_id
+        job_deque = self.unscheduled_operations_per_job[job_id]
+        if job_deque:
+            job_deque.popleft()
+
+    def reset(self) -> None:
+        """Resets unscheduled operations to include all operations.
+
+        This method reinitializes the list of deques with all operations
+        from all jobs in the instance.
+        """
+        self.unscheduled_operations_per_job = [
+            collections.deque(job) for job in self.dispatcher.instance.jobs
+        ]

job_shop_lib/dispatching/feature_observers/__init__.py

@@ -1,16 +1,53 @@
-"""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
+"""Contains :class:`FeatureObserver` classes for observing features of the
+dispatcher.
+
+.. autosummary::
+    :nosignatures:
+
+    FeatureObserver
+    FeatureType
+    CompositeFeatureObserver
+    EarliestStartTimeObserver
+    IsReadyObserver
+    DurationObserver
+    IsScheduledObserver
+    PositionInJobObserver
+    RemainingOperationsObserver
+    IsCompletedObserver
+    FeatureObserverType
+    feature_observer_factory
+    FeatureObserverConfig
+
+A :class:`~job_shop_lib.dispatching.feature_observers.FeatureObserver` is a
+a subclass of :class:`~job_shop_lib.dispatching.DispatcherObserver` that
+observes features related to operations, machines, or jobs in the dispatcher.
+
+Attributes are stored in numpy arrays with a shape of (``num_entities``,
+``feature_size``), where ``num_entities`` is the number of entities being
+observed (e.g., operations, machines, or jobs) and ``feature_size`` is the
+number of values being observed for each entity.
+
+The advantage of using arrays is that they can be easily updated in a
+vectorized manner, which is more efficient than updating each attribute
+individually. Furthermore, machine learning models can be trained on these
+arrays to predict the best dispatching decisions.
+"""
+
+from ._feature_observer import FeatureObserver, FeatureType
+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,
+    FeatureObserverConfig,
+)
+from ._composite_feature_observer import CompositeFeatureObserver
+
 
 __all__ = [
     "FeatureObserver",
@@ -25,4 +62,5 @@ __all__ = [
     "IsCompletedObserver",
     "FeatureObserverType",
     "feature_observer_factory",
+    "FeatureObserverConfig",
 ]