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

job_shop_lib/dispatching/feature_observers/_composite_feature_observer.py

@@ -0,0 +1,212 @@
+"""Home of the `CompositeFeatureObserver` class."""
+
+from collections import defaultdict
+from collections.abc import Sequence
+from typing import List, Dict, Union, Optional, Type
+# The Self type can be imported directly from Python’s typing module in
+# version 3.11 and beyond. We use the typing_extensions module to support
+# python >=3.8
+from typing_extensions import Self
+import numpy as np
+from numpy.typing import NDArray
+import pandas as pd
+
+from job_shop_lib.exceptions import ValidationError
+from job_shop_lib.dispatching import Dispatcher
+from job_shop_lib.dispatching.feature_observers import (
+    FeatureObserver,
+    FeatureType,
+    FeatureObserverConfig,
+    feature_observer_factory,
+    FeatureObserverType,
+)
+
+
+class CompositeFeatureObserver(FeatureObserver):
+    """Aggregates features from other FeatureObserver instances subscribed to
+    the same :class:`~job_shop_lib.dispatching.Dispatcher` by concatenating
+    their feature matrices along the first axis (horizontal concatenation).
+
+    It provides also a custom ``__str__`` method to display the features
+    in a more readable way.
+
+    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.
+        feature_observers:
+            A list of `FeatureObserver` instances to aggregate features from.
+            If ``None``, all feature observers subscribed to the dispatcher are
+            used.
+
+    .. seealso::
+
+        An example using this class can be found in the
+        :doc:`../examples/08-Feature-Observers` example.
+
+        Additionally, the class
+        :class:`~job_shop_lib.reinforcement_learning.SingleJobShopGraphEnv`
+        uses this feature observer to aggregate features from multiple
+        ones.
+
+    """
+
+    __slots__ = {
+        "feature_observers": (
+            "List of :class:`FeatureObserver` instances to aggregate features "
+            "from."
+        ),
+        "column_names": (
+            "Dictionary mapping :class:`FeatureType` to a list of column "
+            "names for the corresponding feature matrix. They are generated "
+            "based on the class name of the :class:`FeatureObserver` instance "
+            "that produced the feature."
+        ),
+    }
+
+    def __init__(
+        self,
+        dispatcher: Dispatcher,
+        *,
+        subscribe: bool = True,
+        feature_types: Optional[Union[List[FeatureType], FeatureType]] = None,
+        feature_observers: Optional[List[FeatureObserver]] = None,
+    ):
+        if feature_observers is None:
+            feature_observers = [
+                observer
+                for observer in dispatcher.subscribers
+                if isinstance(observer, FeatureObserver)
+            ]
+        feature_types = self._get_feature_types_list(feature_types)
+        for observer in feature_observers:
+            if not set(observer.features.keys()).issubset(set(feature_types)):
+                raise ValidationError(
+                    "The feature types observed by the feature observer "
+                    f"{observer.__class__.__name__} are not a subset of the "
+                    "feature types specified in the CompositeFeatureObserver."
+                    f"Observer feature types: {observer.features.keys()}"
+                    f"Composite feature types: {feature_types}"
+                )
+        self.feature_observers = feature_observers
+        self.column_names: Dict[FeatureType, List[str]] = defaultdict(list)
+        super().__init__(dispatcher, subscribe=subscribe)
+        self._set_column_names()
+
+    @classmethod
+    def from_feature_observer_configs(
+        cls,
+        dispatcher: Dispatcher,
+        feature_observer_configs: Sequence[
+            Union[
+                str,
+                FeatureObserverType,
+                Type[FeatureObserver],
+                FeatureObserverConfig,
+            ],
+        ],
+        subscribe: bool = True,
+    ) -> Self:
+        """Creates the composite feature observer.
+
+        Args:
+            dispatcher:
+                The dispatcher used to create the feature observers.
+            feature_observer_configs:
+                The list of feature observer configuration objects.
+            subscribe:
+                Whether to subscribe the CompositeFeatureObserver to the
+                dispatcher.
+        """
+        observers = [
+            feature_observer_factory(observer_config, dispatcher=dispatcher)
+            for observer_config in feature_observer_configs
+        ]
+        composite_observer = cls(
+            dispatcher, feature_observers=observers, subscribe=subscribe
+        )
+        return composite_observer
+
+    @property
+    def features_as_dataframe(self) -> Dict[FeatureType, pd.DataFrame]:
+        """Returns the features as a dictionary of `pd.DataFrame` instances."""
+        return {
+            feature_type: pd.DataFrame(
+                feature_matrix, columns=self.column_names[feature_type]
+            )
+            for feature_type, feature_matrix in self.features.items()
+        }
+
+    def initialize_features(self):
+        features: Dict[FeatureType, List[NDArray[np.float32]]] = defaultdict(
+            list
+        )
+        for observer in self.feature_observers:
+            for feature_type, feature_matrix in observer.features.items():
+                features[feature_type].append(feature_matrix)
+
+        self.features = {
+            feature_type: np.concatenate(features, axis=1)
+            for feature_type, features in features.items()
+        }
+
+    def _set_column_names(self):
+        for observer in self.feature_observers:
+            for feature_type, feature_matrix in observer.features.items():
+                feature_name = observer.__class__.__name__.replace(
+                    "Observer", ""
+                )
+                if feature_matrix.shape[1] > 1:
+                    self.column_names[feature_type] += [
+                        f"{feature_name}_{i}"
+                        for i in range(feature_matrix.shape[1])
+                    ]
+                else:
+                    self.column_names[feature_type].append(feature_name)
+
+    def __str__(self):
+        out = [f"{self.__class__.__name__}:"]
+        out.append("-" * (len(out[0]) - 1))
+        for feature_type, dataframe in self.features_as_dataframe.items():
+            out.append(f"{feature_type.value}:")
+            out.append(dataframe.to_string())
+        return "\n".join(out)
+
+
+if __name__ == "__main__":
+    # from cProfile import Profile
+    import time
+    from job_shop_lib.benchmarking import load_benchmark_instance
+    from job_shop_lib.dispatching.rules import DispatchingRuleSolver
+
+    ta80 = load_benchmark_instance("ta80")
+
+    dispatcher_ = Dispatcher(ta80)
+    feature_observer_types_ = list(FeatureObserverType)
+    feature_observers_ = [
+        feature_observer_factory(
+            observer_type,
+            dispatcher=dispatcher_,
+        )
+        for observer_type in feature_observer_types_
+        # and not FeatureObserverType.EARLIEST_START_TIME
+    ]
+    composite_observer_ = CompositeFeatureObserver(
+        dispatcher_, feature_observers=feature_observers_
+    )
+    solver = DispatchingRuleSolver(dispatching_rule="random")
+    # profiler = Profile()
+    # profiler.runcall(solver.solve, dispatcher_.instance, dispatcher_)
+    # profiler.print_stats("cumtime")
+    start = time.perf_counter()
+    solver.solve(dispatcher_.instance, dispatcher_)
+    end = time.perf_counter()
+    print(f"Time: {end - start}")

job_shop_lib/dispatching/feature_observers/{duration_observer.py → _duration_observer.py}

@@ -2,7 +2,6 @@
 
 import numpy as np
 
-from job_shop_lib.dispatching import Dispatcher
 from job_shop_lib import ScheduledOperation
 from job_shop_lib.dispatching.feature_observers import (
     FeatureObserver,
@@ -13,29 +12,32 @@ from job_shop_lib.dispatching.feature_observers import (
 class DurationObserver(FeatureObserver):
     """Measures the remaining duration of operations, machines, and jobs.
 
-    The duration of an Operation is:
+    The duration of an :class:`~job_shop_lib.Operation` is:
         - if the operation has not been scheduled, it is the duration of the
-        operation.
+          operation.
         - if the operation has been scheduled, it is the remaining duration of
-        the operation.
+          the operation.
         - if the operation has been completed, it is the last duration of the
-        operation that has been computed. The duration must be set to 0
-        manually if needed. We do not update the duration of completed
-        operations to save computation time.
+          operation that has been computed. The duration must be set to 0
+          manually if needed. We do not update the duration of completed
+          operations to save computation time.
 
-    The duration of a Machine or Job is the sum of the durations of the
+    The duration of a machine or job is the sum of the durations of the
     unscheduled operations that belong to the machine or job.
-    """
 
-    def __init__(
-        self,
-        dispatcher: Dispatcher,
-        feature_types: list[FeatureType] | FeatureType | None = None,
-        subscribe: bool = True,
-    ):
-        super().__init__(
-            dispatcher, feature_types, feature_size=1, subscribe=subscribe
-        )
+    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.
+    """
 
     def initialize_features(self):
         mapping = {

job_shop_lib/dispatching/feature_observers/_earliest_start_time_observer.py

@@ -0,0 +1,289 @@
+"""Home of the `EarliestStartTimeObserver` class."""
+
+from typing import List, Optional, Union
+
+import numpy as np
+from numpy.typing import NDArray
+
+from job_shop_lib.dispatching import Dispatcher
+from job_shop_lib.dispatching.feature_observers import (
+    FeatureObserver,
+    FeatureType,
+)
+from job_shop_lib import ScheduledOperation
+
+
+class EarliestStartTimeObserver(FeatureObserver):
+    """Observer that adds a feature indicating the earliest start time of
+    each operation, machine, and job in the graph.
+
+    The earliest start time of an operation refers to the earliest time at
+    which the operation could potentially start without violating any
+    constraints. This time is normalized by the current time (i.e., the
+    difference between the earliest start time and the current time).
+
+    The earliest start time of a machine is the earliest start time of the
+    next operation that can be scheduled on that machine.
+
+    Finally, the earliest start time of a job is the earliest start time of the
+    next operation in the job.
+
+    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.
+    """
+
+    __slots__ = {
+        "earliest_start_times": (
+            "A 2D numpy array with the earliest start "
+            "times of each operation. The array has "
+            "shape (``num_jobs``, ``max_operations_per_job``). "
+            "The value at index (i, j) is the earliest start "
+            "time of the j-th operation in the i-th job. "
+            "If a job has fewer than the maximum number of "
+            "operations in a job, the remaining values are "
+            "set to ``np.nan``. Similarly to "
+            ":class:`~job_shop_lib.JobShopInstance`'s "
+            ":meth:`~job_shop_lib.JobShopInstance.durations_matrix_array` "
+            "method."
+        ),
+        "_job_ids": (
+            "An array that stores the job IDs for each operation in the "
+            "dispatcher's instance. The array has shape "
+            "(``num_machines``, ``max_operations_per_machine``)."
+        ),
+        "_positions": (
+            "An array that stores the positions of each operation in their "
+            "respective jobs. The array has shape "
+            "(``num_machines``, ``max_operations_per_machine``)."
+        ),
+        "_is_regular_instance": (
+            "Whether the dispatcher's instance is a regular "
+            "instance, where each job has the same number of operations."
+        ),
+    }
+
+    def __init__(
+        self,
+        dispatcher: Dispatcher,
+        *,
+        subscribe: bool = True,
+        feature_types: Optional[Union[List[FeatureType], FeatureType]] = None,
+    ):
+
+        # Earliest start times initialization
+        # -------------------------------
+        squared_duration_matrix = dispatcher.instance.durations_matrix_array
+        self.earliest_start_times: NDArray[np.float32] = np.hstack(
+            (
+                np.zeros((squared_duration_matrix.shape[0], 1), dtype=float),
+                np.cumsum(squared_duration_matrix[:, :-1], axis=1),
+            )
+        )
+        self.earliest_start_times[np.isnan(squared_duration_matrix)] = np.nan
+        # -------------------------------
+
+        # Cache:
+        operations_by_machine = dispatcher.instance.operations_by_machine
+        self._is_regular_instance = all(
+            len(job) == len(dispatcher.instance.jobs[0])
+            for job in dispatcher.instance.jobs
+        )
+        if self._is_regular_instance:
+            self._job_ids = np.array(
+                [
+                    [op.job_id for op in machine_ops]
+                    for machine_ops in operations_by_machine
+                ]
+            )
+            self._positions = np.array(
+                [
+                    [op.position_in_job for op in machine_ops]
+                    for machine_ops in operations_by_machine
+                ]
+            )
+        else:
+            self._job_ids = np.array([])
+            self._positions = np.array([])
+
+        super().__init__(
+            dispatcher, feature_types=feature_types, subscribe=subscribe
+        )
+
+    def update(self, scheduled_operation: ScheduledOperation):
+        """Recomputes the earliest start times and calls the
+        ``initialize_features`` method.
+
+        The earliest start times is computed as the cumulative sum of the
+        previous unscheduled operations in the job plus the maximum of the
+        completion time of the last scheduled operation and the next available
+        time of the machine(s) the operation is assigned.
+
+        After that, we substract the current time.
+
+        Args:
+            scheduled_operation: The operation that has been scheduled.
+        """
+        # We compute the gap that the current scheduled operation could be
+        # adding to each job.
+        job_id = scheduled_operation.job_id
+        next_operation_idx = self.dispatcher.job_next_operation_index[job_id]
+        if next_operation_idx < len(self.dispatcher.instance.jobs[job_id]):
+            old_start_time = self.earliest_start_times[
+                job_id, next_operation_idx
+            ]
+            next_operation = self.dispatcher.instance.jobs[job_id][
+                next_operation_idx
+            ]
+            new_start_time = max(
+                scheduled_operation.end_time,
+                old_start_time,
+                self.dispatcher.earliest_start_time(next_operation),
+            )
+            gap = new_start_time - old_start_time
+            self.earliest_start_times[job_id, next_operation_idx:] += gap
+
+        # Now, we compute the gap that could be introduced by the new
+        # next_available_time of the machine.
+        machine_ops = self.dispatcher.instance.operations_by_machine[
+            scheduled_operation.machine_id
+        ]
+        unscheduled_mask = np.array(
+            [not self.dispatcher.is_scheduled(op) for op in machine_ops]
+        )
+        if np.any(unscheduled_mask):
+            if self._job_ids.size == 0:
+                job_ids = np.array([op.job_id for op in machine_ops])[
+                    unscheduled_mask
+                ]
+            else:
+                job_ids = self._job_ids[scheduled_operation.machine_id][
+                    unscheduled_mask
+                ]
+
+            if self._positions.size == 0:
+                positions = np.array(
+                    [op.position_in_job for op in machine_ops]
+                )[unscheduled_mask]
+            else:
+                positions = self._positions[scheduled_operation.machine_id][
+                    unscheduled_mask
+                ]
+            old_start_times = self.earliest_start_times[job_ids, positions]
+            new_start_times = np.maximum(
+                scheduled_operation.end_time, old_start_times
+            )
+            gaps = new_start_times - old_start_times
+
+            for job_id, position, gap in zip(job_ids, positions, gaps):
+                self.earliest_start_times[job_id, position:] += gap
+
+        self.initialize_features()
+
+    def initialize_features(self):
+        """Initializes the features based on the current state of the
+        dispatcher."""
+        for feature_type in self.features:
+            if feature_type == FeatureType.OPERATIONS:
+                self._update_operation_features()
+            elif (
+                feature_type == FeatureType.MACHINES
+                and self._is_regular_instance
+            ):
+                self._update_machine_features_vectorized()
+            elif feature_type == FeatureType.MACHINES:
+                self._update_machine_features()
+            elif feature_type == FeatureType.JOBS:
+                self._update_job_features()
+
+    def _update_operation_features(self):
+        """Ravels the 2D array into a 1D array"""
+        current_time = self.dispatcher.current_time()
+        next_index = 0
+        for job_id, operations in enumerate(self.dispatcher.instance.jobs):
+            self.features[FeatureType.OPERATIONS][
+                next_index : next_index + len(operations), 0
+            ] = (
+                self.earliest_start_times[job_id, : len(operations)]
+                - current_time
+            )
+            next_index += len(operations)
+
+    def _update_machine_features(self):
+        """Picks the minimum start time of all operations that can be scheduled
+        on that machine"""
+        current_time = self.dispatcher.current_time()
+        operations_by_machine = self.dispatcher.instance.operations_by_machine
+        for machine_id, operations in enumerate(operations_by_machine):
+            min_earliest_start_time = min(
+                (
+                    self.earliest_start_times[
+                        operation.job_id, operation.position_in_job
+                    ]
+                    for operation in operations
+                    if not self.dispatcher.is_scheduled(operation)
+                ),
+                default=0,
+            )
+            self.features[FeatureType.MACHINES][machine_id, 0] = (
+                min_earliest_start_time - current_time
+            )
+
+    def _update_machine_features_vectorized(self):
+        """Picks the minimum start time of all operations that can be scheduled
+        on that machine"""
+        current_time = self.dispatcher.current_time()
+        operations_by_machine = self.dispatcher.instance.operations_by_machine
+
+        # Create a mask for unscheduled operations
+        is_unscheduled = np.array(
+            [
+                [not self.dispatcher.is_scheduled(op) for op in machine_ops]
+                for machine_ops in operations_by_machine
+            ]
+        )
+
+        # Get earliest start times for all operations
+        earliest_start_times = self.earliest_start_times[
+            self._job_ids, self._positions
+        ]
+
+        # Apply mask for unscheduled operations
+        masked_start_times = np.where(
+            is_unscheduled, earliest_start_times, np.inf
+        )
+
+        # Find minimum start time for each machine
+        min_start_times = np.min(masked_start_times, axis=1)
+
+        # Handle cases where all operations are scheduled
+        min_start_times = np.where(
+            np.isinf(min_start_times), 0, min_start_times
+        )
+
+        self.features[FeatureType.MACHINES][:, 0] = (
+            min_start_times - current_time
+        )
+
+    def _update_job_features(self):
+        """Picks the earliest start time of the next operation in the job"""
+        current_time = self.dispatcher.current_time()
+        for job_id, next_operation_idx in enumerate(
+            self.dispatcher.job_next_operation_index
+        ):
+            job_length = len(self.dispatcher.instance.jobs[job_id])
+            if next_operation_idx == job_length:
+                continue
+            self.features[FeatureType.JOBS][job_id, 0] = (
+                self.earliest_start_times[job_id, next_operation_idx]
+                - current_time
+            )

job_shop_lib/dispatching/feature_observers/_factory.py

@@ -0,0 +1,95 @@
+"""Contains factory functions for creating :class:`FeatureObserver`s."""
+
+from enum import Enum
+from typing import Union, Type
+
+from job_shop_lib.dispatching import DispatcherObserverConfig
+from job_shop_lib.dispatching.feature_observers import (
+    IsReadyObserver,
+    EarliestStartTimeObserver,
+    FeatureObserver,
+    DurationObserver,
+    IsScheduledObserver,
+    PositionInJobObserver,
+    RemainingOperationsObserver,
+    IsCompletedObserver,
+)
+
+
+class FeatureObserverType(str, Enum):
+    """Enumeration of the different feature observers.
+
+    Each :class:`FeatureObserver` is associated with a string value that can be
+    used to create the :class:`FeatureObserver` using the factory function.
+
+    It does not include the :class:`CompositeFeatureObserver` class since this
+    observer is often managed separately from the others. For example, a
+    common use case is to create a list of feature observers and pass them to
+    """
+
+    IS_READY = "is_ready"
+    EARLIEST_START_TIME = "earliest_start_time"
+    DURATION = "duration"
+    IS_SCHEDULED = "is_scheduled"
+    POSITION_IN_JOB = "position_in_job"
+    REMAINING_OPERATIONS = "remaining_operations"
+    IS_COMPLETED = "is_completed"
+
+
+# FeatureObserverConfig = DispatcherObserverConfig[
+#     Type[FeatureObserver] | FeatureObserverType | str
+# ]
+# FeatureObserverConfig = DispatcherObserverConfig[
+#     Union[Type[FeatureObserver], FeatureObserverType, str]
+# ]
+FeatureObserverConfig = (
+    DispatcherObserverConfig[Type[FeatureObserver]]
+    | DispatcherObserverConfig[FeatureObserverType]
+    | DispatcherObserverConfig[str]
+)
+
+
+def feature_observer_factory(
+    feature_observer_type: Union[
+        str,
+        FeatureObserverType,
+        Type[FeatureObserver],
+        FeatureObserverConfig
+    ],
+    **kwargs,
+) -> FeatureObserver:
+    """Creates and returns a :class:`FeatureObserver` based on the specified
+    :class:`FeatureObserver` type.
+
+    Args:
+        feature_creator_type:
+            The type of :class:`FeatureObserver` to create.
+        **kwargs:
+            Additional keyword arguments to pass to the
+            :class:`FeatureObserver` constructor.
+
+    Returns:
+        A :class:`FeatureObserver` instance.
+    """
+    if isinstance(feature_observer_type, DispatcherObserverConfig):
+        return feature_observer_factory(
+            feature_observer_type.class_type,
+            **feature_observer_type.kwargs,
+            **kwargs,
+        )
+    # if the instance is of type Type[FeatureObserver] we can just
+    # call the object constructor with the keyword arguments
+    if isinstance(feature_observer_type, type):
+        return feature_observer_type(**kwargs)
+
+    mapping: dict[FeatureObserverType, Type[FeatureObserver]] = {
+        FeatureObserverType.IS_READY: IsReadyObserver,
+        FeatureObserverType.EARLIEST_START_TIME: EarliestStartTimeObserver,
+        FeatureObserverType.DURATION: DurationObserver,
+        FeatureObserverType.IS_SCHEDULED: IsScheduledObserver,
+        FeatureObserverType.POSITION_IN_JOB: PositionInJobObserver,
+        FeatureObserverType.REMAINING_OPERATIONS: RemainingOperationsObserver,
+        FeatureObserverType.IS_COMPLETED: IsCompletedObserver,
+    }
+    feature_observer = mapping[feature_observer_type]  # type: ignore[index]
+    return feature_observer(**kwargs)