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

job_shop_lib/dispatching/feature_observers/_feature_observer.py

@@ -0,0 +1,228 @@
+"""Home of the `FeatureObserver` class and `FeatureType` enum."""
+
+import enum
+from typing import Optional, Union, Dict, List, Tuple
+
+import numpy as np
+
+from job_shop_lib import ScheduledOperation
+from job_shop_lib.exceptions import ValidationError
+from job_shop_lib.dispatching import Dispatcher, DispatcherObserver
+
+
+class FeatureType(str, enum.Enum):
+    """Types of features that can be extracted."""
+
+    OPERATIONS = "operations"
+    MACHINES = "machines"
+    JOBS = "jobs"
+
+
+class FeatureObserver(DispatcherObserver):
+    """Base class for feature observers.
+
+    A :class:`FeatureObserver` is a
+    a subclass of :class:`~job_shop_lib.dispatching.DispatcherObserver` that
+    observes features related to operations, machines, or jobs in the
+    :class:`~job_shop_lib.dispatching.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.
+
+    Arrays use the data type ``np.float32``.
+
+    New :class:`FeatureObservers` must inherit from this class, and re-define
+    the class attributes ``_singleton`` (defualt ), ``_feature_size``
+    (default 1) and ``_supported_feature_types`` (default all feature types).
+
+    Feature observers are not singleton by default. This means that more than
+    one instance of the same feature observer type can be subscribed to the
+    dispatcher. This is useful when the first subscriber only observes a subset
+    of the features, and the second subscriber observes a different subset of
+    them. For example, the first subscriber could observe only the
+    operation-related features, while the second subscriber could observe the
+    jobs.
+
+    Args:
+        dispatcher:
+            The :class:`~job_shop_lib.dispatching.Dispatcher` to observe.
+        subscribe:
+            If ``True``, the observer is subscribed to the dispatcher upon
+            initialization. Otherwise, the observer must be subscribed later
+            or manually updated.
+        feature_types:
+            A list of :class:`FeatureType` or a single :class:`FeatureType`
+            that specifies the types of features to observe. They must be a
+            subset of the class attribute :attr:`supported_feature_types`.
+            If ``None``, all supported feature types are tracked.
+    """
+
+    _is_singleton = False
+    _feature_sizes: Union[Dict[FeatureType, int], int] = 1
+    _supported_feature_types = list(FeatureType)
+
+    __slots__ = {
+        "features": (
+            "A dictionary of numpy arrays with the features. "
+            "Each key is a :class:`FeatureType` and each value is a numpy "
+            "array with the features. The array has shape (``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."
+        )
+    }
+
+    def __init__(
+        self,
+        dispatcher: Dispatcher,
+        *,
+        subscribe: bool = True,
+        feature_types: Optional[Union[List[FeatureType], FeatureType]] = None,
+    ):
+        feature_types = self._get_feature_types_list(feature_types)
+        if isinstance(self._feature_sizes, int):
+            feature_size = {
+                feature_type: self._feature_sizes
+                for feature_type in feature_types
+            }
+        super().__init__(dispatcher, subscribe=subscribe)
+
+        number_of_entities = {
+            FeatureType.OPERATIONS: dispatcher.instance.num_operations,
+            FeatureType.MACHINES: dispatcher.instance.num_machines,
+            FeatureType.JOBS: dispatcher.instance.num_jobs,
+        }
+        feature_dimensions = {
+            feature_type: (
+                number_of_entities[feature_type],
+                feature_size[feature_type],
+            )
+            for feature_type in feature_types
+        }
+        self.features = {
+            feature_type: np.zeros(
+                feature_dimensions[feature_type],
+                dtype=np.float32,
+            )
+            for feature_type in feature_types
+        }
+        self.initialize_features()
+
+    @property
+    def feature_sizes(self) -> Dict[FeatureType, int]:
+        """Returns the size of the features.
+
+        The size of the features is the number of values being observed for
+        each entity. This corresponds to the second dimension of each array.
+
+        This number is typically one (e.g. measuring the duration
+        of each operation), but some feature observers like the
+        :class:`CompositeFeatureObserver` may track more than one value.
+        """
+        if isinstance(self._feature_sizes, int):
+            return {
+                feature_type: self._feature_sizes
+                for feature_type in self.features
+            }
+        return self._feature_sizes
+
+    @property
+    def supported_feature_types(self) -> List[FeatureType]:
+        """Returns the supported feature types."""
+        return self._supported_feature_types
+
+    @property
+    def feature_dimensions(self) -> Dict[FeatureType, Tuple[int, int]]:
+        """A dictionary containing the shape of each :class:`FeatureType`."""
+        feature_dimensions = {}
+        for feature_type, array in self.features.items():
+            feature_dimensions[feature_type] = array.shape
+        return feature_dimensions  # type: ignore[return-value]
+
+    def initialize_features(self):
+        """Initializes the features based on the current state of the
+        dispatcher.
+
+        This method is automatically called after initializing the observer.
+        """
+
+    def update(self, scheduled_operation: ScheduledOperation):
+        """Updates the features based on the scheduled operation.
+
+        By default, this method just calls :meth:`initialize_features`.
+
+        Args:
+            ScheduledOperation:
+                The operation that has been scheduled.
+        """
+        self.initialize_features()
+
+    def reset(self):
+        """Sets features to zero and calls to :meth:``initialize_features``."""
+        self.set_features_to_zero()
+        self.initialize_features()
+
+    def set_features_to_zero(
+        self, exclude: Optional[Union[FeatureType, List[FeatureType]]] = None
+    ):
+        """Sets all features to zero except for the ones specified in
+        ``exclude``.
+
+        Setting a feature to zero means that all values in the feature array
+        are set to this value.
+
+        Args:
+            exclude:
+                A single :class:`FeatureType` or a list of :class:`FeatureType`
+                that specifies the features that should not be set to zero. If
+                ``None``, all currently used features are set to zero.
+        """
+        if exclude is None:
+            exclude = []
+        if isinstance(exclude, FeatureType):
+            exclude = [exclude]
+
+        for feature_type in self.features:
+            if feature_type in exclude:
+                continue
+            self.features[feature_type][:] = 0.0
+
+    def _get_feature_types_list(
+        self,
+        feature_types: Optional[Union[List[FeatureType], FeatureType]],
+    ) -> List[FeatureType]:
+        """Returns a list of feature types.
+
+        Args:
+            feature_types:
+                A list of feature types or a single feature type. If ``None``,
+                all feature types are returned.
+        """
+        if isinstance(feature_types, FeatureType):
+            return [feature_types]
+        if feature_types is None:
+            return self._supported_feature_types
+
+        for feature_type in feature_types:
+            if feature_type not in self._supported_feature_types:
+                raise ValidationError(
+                    f"Feature type {feature_type} is not supported."
+                    " Supported feature types are: "
+                    f"{self._supported_feature_types}"
+                )
+        return feature_types
+
+    def __str__(self):
+        out = [self.__class__.__name__, ":\n"]
+        out.append("-" * len(out[0]))
+        for feature_type, feature in self.features.items():
+            out.append(f"\n{feature_type.value}:\n{feature}")
+        return "".join(out)

job_shop_lib/dispatching/feature_observers/_is_completed_observer.py

@@ -0,0 +1,97 @@
+"""Home of the `IsCompletedObserver` class."""
+
+from typing import Optional, Union, List
+import numpy as np
+
+from job_shop_lib import ScheduledOperation
+from job_shop_lib.dispatching import Dispatcher
+from job_shop_lib.dispatching.feature_observers import (
+    FeatureObserver,
+    FeatureType,
+)
+
+
+class IsCompletedObserver(FeatureObserver):
+    """Adds a binary feature indicating whether each operation,
+    machine, or job has been completed.
+
+    An operation is considered completed if it has been scheduled and the
+    current time is greater than or equal to the sum of the operation's start
+    time and duration.
+
+    A machine or job is considered completed if all of its operations have been
+    completed.
+
+    Args:
+        dispatcher:
+            The :class:`~job_shop_lib.dispatching.Dispatcher` to observe.
+        feature_types:
+            A list of :class:`FeatureType` or a single :class:`FeatureType`
+            that specifies the types of features to observe. They must be a
+            subset of the class attribute :attr:`supported_feature_types`.
+            If ``None``, all supported feature types are tracked.
+        subscribe:
+            If ``True``, the observer is subscribed to the dispatcher upon
+            initialization. Otherwise, the observer must be subscribed later
+            or manually updated.
+    """
+
+    def __init__(
+        self,
+        dispatcher: Dispatcher,
+        *,
+        feature_types: Optional[Union[List[FeatureType], FeatureType]] = None,
+        subscribe: bool = True,
+    ):
+        feature_types = self._get_feature_types_list(feature_types)
+        self._num_of_operations_per_machine = np.array(
+            [
+                len(operations_by_machine)
+                for operations_by_machine in (
+                    dispatcher.instance.operations_by_machine
+                )
+            ]
+        )
+        self._num_of_operations_per_job = np.array(
+            [len(job) for job in dispatcher.instance.jobs]
+        )
+        super().__init__(
+            dispatcher,
+            feature_types=feature_types,
+            subscribe=subscribe,
+        )
+
+    def initialize_features(self):
+        if FeatureType.OPERATIONS in self.features:
+            completed_operations = [
+                op.operation.operation_id
+                for op in self.dispatcher.completed_operations()
+            ]
+            self.features[FeatureType.OPERATIONS][completed_operations, 0] = 1
+        if FeatureType.MACHINES in self.features:
+            num_completed_ops_per_machine = np.zeros(
+                len(self._num_of_operations_per_machine)
+            )
+            for op in self.dispatcher.completed_operations():
+                for machine_id in op.operation.machines:
+                    num_completed_ops_per_machine[machine_id] += 1
+            self.features[FeatureType.MACHINES][:, 0] = (
+                num_completed_ops_per_machine
+                == self._num_of_operations_per_machine
+            ).astype(np.float32)
+        if FeatureType.JOBS in self.features:
+            num_completed_ops_per_job = np.zeros(
+                len(self._num_of_operations_per_job)
+            )
+            for op in self.dispatcher.completed_operations():
+                num_completed_ops_per_job[op.operation.job_id] += 1
+            self.features[FeatureType.JOBS][:, 0] = (
+                num_completed_ops_per_job
+                == self._num_of_operations_per_job
+            ).astype(np.float32)
+
+    def reset(self):
+        self.set_features_to_zero()
+
+    def update(self, scheduled_operation: ScheduledOperation):
+        self.initialize_features()

job_shop_lib/dispatching/feature_observers/_is_ready_observer.py

@@ -0,0 +1,35 @@
+"""Home of the `IsReadyObserver` class."""
+
+from typing import List
+
+from job_shop_lib.dispatching.feature_observers import (
+    FeatureObserver,
+    FeatureType,
+)
+
+
+class IsReadyObserver(FeatureObserver):
+    """Feature creator that adds a binary feature indicating if the operation,
+    machine or job is ready to be dispatched."""
+
+    def initialize_features(self):
+        self.set_features_to_zero()
+        for feature_type, feature in self.features.items():
+            feature_ids = self._get_ready_feature_ids(feature_type)
+            feature[feature_ids, 0] = 1.0
+
+    def _get_ready_feature_ids(self, feature_type: FeatureType) -> List[int]:
+        if feature_type == FeatureType.OPERATIONS:
+            return self._get_ready_operations()
+        if feature_type == FeatureType.MACHINES:
+            return self.dispatcher.available_machines()
+        if feature_type == FeatureType.JOBS:
+            return self.dispatcher.available_jobs()
+        raise ValueError(f"Feature type {feature_type} is not supported.")
+
+    def reset(self):
+        self.initialize_features()
+
+    def _get_ready_operations(self) -> List[int]:
+        available_operations = self.dispatcher.available_operations()
+        return [operation.operation_id for operation in available_operations]

job_shop_lib/dispatching/feature_observers/{is_scheduled_observer.py → _is_scheduled_observer.py}

@@ -8,14 +8,18 @@ from job_shop_lib.dispatching.feature_observers import (
 
 
 class IsScheduledObserver(FeatureObserver):
-    """Observer that updates features based on scheduling operations.
+    """Updates features based on scheduling operations.
 
     This observer tracks which operations have been scheduled and updates
-    feature matrices accordingly. It updates a feature in the
-    `FeatureType.OPERATIONS` matrix to indicate that an operation has been
-    scheduled. Additionally, it counts the number of uncompleted but
+    feature matrices accordingly.
+
+    It updates a feature in the
+    :meth:`FeatureType.OPERATIONS` matrix to indicate that an operation has
+    been scheduled.
+
+    Additionally, it counts the number of uncompleted but
     scheduled operations for each machine and job, updating the respective
-    `FeatureType.MACHINES` and `FeatureType.JOBS` feature matrices.
+    :meth:`FeatureType.MACHINES` and :meth:`FeatureType.JOBS` feature matrices.
     """
 
     def update(self, scheduled_operation: ScheduledOperation):

job_shop_lib/dispatching/feature_observers/{position_in_job_observer.py → _position_in_job_observer.py}

@@ -1,6 +1,5 @@
 """Home of the `PositionInJobObserver` class."""
 
-from job_shop_lib.dispatching import Dispatcher
 from job_shop_lib import ScheduledOperation
 from job_shop_lib.dispatching.feature_observers import (
     FeatureObserver,
@@ -9,19 +8,18 @@ from job_shop_lib.dispatching.feature_observers import (
 
 
 class PositionInJobObserver(FeatureObserver):
-    """Observer that adds a feature indicating the position of
+    """Adds a feature indicating the position of
     operations in their respective jobs.
 
-    Positions are adjusted dynamically as operations are scheduled.
+    Positions are adjusted dynamically as operations are scheduled. In other
+    words, the position of an operation is the number of unscheduled operations
+    that precede it in the job.
+
+    It only supports the :meth:`~job_shop_lib.FeatureType.OPERATIONS` feature
+    type.
     """
 
-    def __init__(self, dispatcher: Dispatcher, subscribe: bool = True):
-        super().__init__(
-            dispatcher,
-            feature_types=[FeatureType.OPERATIONS],
-            feature_size=1,
-            subscribe=subscribe,
-        )
+    _supported_feature_types = [FeatureType.OPERATIONS]
 
     def initialize_features(self):
         for operation in self.dispatcher.unscheduled_operations():

job_shop_lib/dispatching/feature_observers/{remaining_operations_observer.py → _remaining_operations_observer.py}

@@ -1,7 +1,7 @@
 """Home of the `RemainingOperationsObserver` class."""
 
 from job_shop_lib import ScheduledOperation
-from job_shop_lib.dispatching import Dispatcher
+from job_shop_lib.dispatching import UnscheduledOperationsObserver
 from job_shop_lib.dispatching.feature_observers import (
     FeatureObserver,
     FeatureType,
@@ -12,38 +12,20 @@ class RemainingOperationsObserver(FeatureObserver):
     """Adds a feature indicating the number of remaining operations for each
     job and machine.
 
-    It does not support FeatureType.OPERATIONS.
+    It does not support :meth:`FeatureType.OPERATIONS`.
     """
 
-    def __init__(
-        self,
-        dispatcher: Dispatcher,
-        feature_types: list[FeatureType] | FeatureType | None = None,
-        subscribe: bool = True,
-    ):
-        if feature_types is None:
-            feature_types = [FeatureType.MACHINES, FeatureType.JOBS]
-
-        if (
-            feature_types == FeatureType.OPERATIONS
-            or FeatureType.OPERATIONS in feature_types
-        ):
-            raise ValueError("FeatureType.OPERATIONS is not supported.")
-        super().__init__(
-            dispatcher,
-            feature_types=feature_types,
-            feature_size=1,
-            subscribe=subscribe,
-        )
+    _supported_feature_types = [FeatureType.MACHINES, FeatureType.JOBS]
 
     def initialize_features(self):
-        for operation in self.dispatcher.unscheduled_operations():
+        unscheduled_ops_observer = self.dispatcher.create_or_get_observer(
+            UnscheduledOperationsObserver
+        )
+        for operation in unscheduled_ops_observer.unscheduled_operations:
             if FeatureType.JOBS in self.features:
                 self.features[FeatureType.JOBS][operation.job_id, 0] += 1
             if FeatureType.MACHINES in self.features:
-                self.features[FeatureType.MACHINES][
-                    operation.machine_id, 0
-                ] += 1
+                self.features[FeatureType.MACHINES][operation.machines, 0] += 1
 
     def update(self, scheduled_operation: ScheduledOperation):
         if FeatureType.JOBS in self.features:

job_shop_lib/dispatching/rules/__init__.py

@@ -0,0 +1,87 @@
+"""Contains the dispatching rules for the job shop scheduling problem.
+
+Main objects:
+
+.. autosummary::
+
+    DispatchingRuleSolver
+    dispatching_rule_factory
+    DispatchingRuleType
+    MachineChooserType
+    dispatching_rule_factory
+    machine_chooser_factory
+
+Dispatching rules:
+
+.. autosummary::
+
+    shortest_processing_time_rule
+    first_come_first_served_rule
+    most_work_remaining_rule
+    most_operations_remaining_rule
+    random_operation_rule
+    score_based_rule
+    score_based_rule_with_tie_breaker
+    observer_based_most_work_remaining_rule
+
+Dispatching rule scorers:
+
+.. autosummary::
+
+    shortest_processing_time_score
+    first_come_first_served_score
+    MostWorkRemainingScorer
+    most_operations_remaining_score
+    random_score
+
+"""
+
+from ._dispatching_rules_functions import (
+    shortest_processing_time_rule,
+    first_come_first_served_rule,
+    most_work_remaining_rule,
+    most_operations_remaining_rule,
+    random_operation_rule,
+    score_based_rule,
+    score_based_rule_with_tie_breaker,
+    shortest_processing_time_score,
+    first_come_first_served_score,
+    MostWorkRemainingScorer,
+    most_operations_remaining_score,
+    random_score,
+    observer_based_most_work_remaining_rule,
+)
+from ._machine_chooser_factory import (
+    MachineChooserType,
+    MachineChooser,
+    machine_chooser_factory,
+)
+
+from ._dispatching_rule_factory import (
+    dispatching_rule_factory,
+    DispatchingRuleType,
+)
+from ._dispatching_rule_solver import DispatchingRuleSolver
+
+
+__all__ = [
+    "shortest_processing_time_rule",
+    "first_come_first_served_rule",
+    "most_work_remaining_rule",
+    "most_operations_remaining_rule",
+    "random_operation_rule",
+    "score_based_rule",
+    "score_based_rule_with_tie_breaker",
+    "shortest_processing_time_score",
+    "first_come_first_served_score",
+    "MostWorkRemainingScorer",
+    "most_operations_remaining_score",
+    "random_score",
+    "dispatching_rule_factory",
+    "DispatchingRuleType",
+    "MachineChooserType",
+    "machine_chooser_factory",
+    "MachineChooser",
+    "DispatchingRuleSolver",
+    "observer_based_most_work_remaining_rule",
+]

job_shop_lib/dispatching/rules/_dispatching_rule_factory.py

@@ -0,0 +1,84 @@
+"""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 Dict, Union
+
+from enum import Enum
+from collections.abc import Callable
+
+from job_shop_lib import Operation
+from job_shop_lib.exceptions import ValidationError
+from job_shop_lib.dispatching import Dispatcher
+from job_shop_lib.dispatching.rules import (
+    shortest_processing_time_rule,
+    first_come_first_served_rule,
+    most_operations_remaining_rule,
+    random_operation_rule,
+    most_work_remaining_rule,
+)
+
+
+class DispatchingRuleType(str, Enum):
+    """Enumeration of dispatching rules for the job shop scheduling problem."""
+
+    SHORTEST_PROCESSING_TIME = "shortest_processing_time"
+    FIRST_COME_FIRST_SERVED = "first_come_first_served"
+    MOST_WORK_REMAINING = "most_work_remaining"
+    MOST_OPERATIONS_REMAINING = "most_operations_remaining"
+    RANDOM = "random"
+
+
+def dispatching_rule_factory(
+    dispatching_rule: Union[str, DispatchingRuleType],
+) -> Callable[[Dispatcher], Operation]:
+    """Creates and returns a dispatching rule function based on the specified
+    dispatching rule name.
+
+    The dispatching rule function determines the order in which operations are
+    selected for execution based on certain criteria such as shortest
+    processing time, first come first served, etc.
+
+    Args:
+        dispatching_rule: The name of the dispatching rule to be used.
+            Supported values are 'shortest_processing_time',
+            'first_come_first_served', 'most_work_remaining',
+            and 'random'.
+
+    Returns:
+        A function that takes a Dispatcher instance as input and returns an
+        Operation based on the specified dispatching rule.
+
+    Raises:
+        ValidationError:
+            If the dispatching_rule argument is not recognized or it is
+            not supported.
+    """
+    dispatching_rules: Dict[
+        DispatchingRuleType,
+        Callable[[Dispatcher], Operation],
+    ] = {
+        DispatchingRuleType.SHORTEST_PROCESSING_TIME: (
+            shortest_processing_time_rule
+        ),
+        DispatchingRuleType.FIRST_COME_FIRST_SERVED: (
+            first_come_first_served_rule
+        ),
+        DispatchingRuleType.MOST_WORK_REMAINING: most_work_remaining_rule,
+        DispatchingRuleType.MOST_OPERATIONS_REMAINING: (
+            most_operations_remaining_rule
+        ),
+        DispatchingRuleType.RANDOM: random_operation_rule,
+    }
+
+    dispatching_rule = dispatching_rule.lower()
+    if dispatching_rule not in dispatching_rules:
+        raise ValidationError(
+            f"Dispatching rule {dispatching_rule} not recognized. Available "
+            f"dispatching rules: {', '.join(dispatching_rules)}."
+        )
+
+    return dispatching_rules[dispatching_rule]  # type: ignore[index]