job-shop-lib 1.0.0a1__py3-none-any.whl → 1.0.0a3__py3-none-any.whl

job_shop_lib/dispatching/feature_observers/_duration_observer.py

@@ -12,7 +12,7 @@ from job_shop_lib.dispatching.feature_observers import (
 class DurationObserver(FeatureObserver):
     """Measures the remaining duration of operations, machines, and jobs.
 
-    The duration of an :class:`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.
         - if the operation has been scheduled, it is the remaining duration of
@@ -22,8 +22,21 @@ class DurationObserver(FeatureObserver):
           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.
+
+    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):

job_shop_lib/dispatching/feature_observers/_earliest_start_time_observer.py

@@ -1,6 +1,7 @@
 """Home of the `EarliestStartTimeObserver` class."""
 
 import numpy as np
+from numpy.typing import NDArray
 
 from job_shop_lib.dispatching import Dispatcher
 from job_shop_lib.dispatching.feature_observers import (
@@ -12,14 +13,62 @@ 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."""
+    each operation, machine, and job in the graph.
 
-    __slots__ = (
-        "earliest_start_times",
-        "_job_ids",
-        "_positions",
-        "machine_ids",
-    )
+    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,
@@ -32,9 +81,9 @@ class EarliestStartTimeObserver(FeatureObserver):
         # Earliest start times initialization
         # -------------------------------
         squared_duration_matrix = dispatcher.instance.durations_matrix_array
-        self.earliest_start_times = np.hstack(
+        self.earliest_start_times: NDArray[np.float32] = np.hstack(
             (
-                np.zeros((squared_duration_matrix.shape[0], 1)),
+                np.zeros((squared_duration_matrix.shape[0], 1), dtype=float),
                 np.cumsum(squared_duration_matrix[:, :-1], axis=1),
             )
         )
@@ -70,7 +119,7 @@ class EarliestStartTimeObserver(FeatureObserver):
 
     def update(self, scheduled_operation: ScheduledOperation):
         """Recomputes the earliest start times and calls the
-        `initialize_features` method.
+        ``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
@@ -78,6 +127,9 @@ class EarliestStartTimeObserver(FeatureObserver):
         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_shop_lib/dispatching/feature_observers/_factory.py

@@ -16,7 +16,11 @@ from job_shop_lib.dispatching.feature_observers import (
 
 
 class FeatureObserverType(str, Enum):
-    """Enumeration of the different feature observers."""
+    """Enumeration of the different feature observers.
+
+    Each feature observer is associated with a string value that can be used
+    to create the feature observer using the factory function.
+    """
 
     IS_READY = "is_ready"
     EARLIEST_START_TIME = "earliest_start_time"

job_shop_lib/dispatching/feature_observers/_feature_observer.py

@@ -20,6 +20,27 @@ class FeatureType(str, enum.Enum):
 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``. This is because most machine
+
+    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
@@ -27,16 +48,36 @@ class FeatureObserver(DispatcherObserver):
     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_size: dict[FeatureType, int] | int = 1
+    _feature_sizes: dict[FeatureType, int] | int = 1
     _supported_feature_types = list(FeatureType)
 
-    __slots__ = (
-        "features",
-        "feature_dimensions",
-    )
+    __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,
@@ -46,9 +87,9 @@ class FeatureObserver(DispatcherObserver):
         feature_types: list[FeatureType] | FeatureType | None = None,
     ):
         feature_types = self._get_feature_types_list(feature_types)
-        if isinstance(self._feature_size, int):
+        if isinstance(self._feature_sizes, int):
             feature_size = {
-                feature_type: self._feature_size
+                feature_type: self._feature_sizes
                 for feature_type in feature_types
             }
         super().__init__(dispatcher, subscribe=subscribe)
@@ -58,7 +99,7 @@ class FeatureObserver(DispatcherObserver):
             FeatureType.MACHINES: dispatcher.instance.num_machines,
             FeatureType.JOBS: dispatcher.instance.num_jobs,
         }
-        self.feature_dimensions = {
+        feature_dimensions = {
             feature_type: (
                 number_of_entities[feature_type],
                 feature_size[feature_type],
@@ -67,7 +108,7 @@ class FeatureObserver(DispatcherObserver):
         }
         self.features = {
             feature_type: np.zeros(
-                self.feature_dimensions[feature_type],
+                feature_dimensions[feature_type],
                 dtype=np.float32,
             )
             for feature_type in feature_types
@@ -75,23 +116,42 @@ class FeatureObserver(DispatcherObserver):
         self.initialize_features()
 
     @property
-    def feature_size(self) -> dict[FeatureType, int]:
-        """Returns the size of the features."""
-        if isinstance(self._feature_size, int):
+    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_size
+                feature_type: self._feature_sizes
                 for feature_type in self.features
             }
-        return self._feature_size
+        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."""
+        dispatcher.
+
+        This method is automatically called after initializing the observer.
+        """
 
     def update(self, scheduled_operation: ScheduledOperation):
         """Updates the features based on the scheduled operation.
@@ -112,7 +172,18 @@ class FeatureObserver(DispatcherObserver):
     def set_features_to_zero(
         self, exclude: FeatureType | list[FeatureType] | None = None
     ):
-        """Sets features to zero."""
+        """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):

job_shop_lib/dispatching/feature_observers/_is_completed_observer.py

@@ -15,8 +15,38 @@ from job_shop_lib.dispatching.feature_observers import (
 
 
 class IsCompletedObserver(FeatureObserver):
-    """Observer that adds a binary feature indicating whether each operation,
-    machine, or job has been completed."""
+    """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.
+    """
+
+    __slots__ = {
+        "remaining_ops_per_machine": (
+            "The number of unscheduled operations per machine."
+        ),
+        "remaining_ops_per_job": (
+            "The number of unscheduled operations per job."
+        ),
+    }
 
     def __init__(
         self,

job_shop_lib/dispatching/feature_observers/_is_ready_observer.py

@@ -7,8 +7,8 @@ from job_shop_lib.dispatching.feature_observers import (
 
 
 class IsReadyObserver(FeatureObserver):
-    """Feature creator that adds a binary feature indicating if the operation
-    is ready to be dispatched."""
+    """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()
@@ -29,5 +29,5 @@ class IsReadyObserver(FeatureObserver):
         self.initialize_features()
 
     def _get_ready_operations(self) -> list[int]:
-        available_operations = self.dispatcher.ready_operations()
+        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

@@ -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

@@ -8,10 +8,15 @@ 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.
     """
 
     _supported_feature_types = [FeatureType.OPERATIONS]

job_shop_lib/dispatching/feature_observers/_remaining_operations_observer.py

@@ -12,7 +12,7 @@ class RemainingOperationsObserver(FeatureObserver):
     """Adds a feature indicating the number of remaining operations for each
     job and machine.
 
-    It does not support :class:`FeatureType.OPERATIONS`.
+    It does not support :meth:`FeatureType.OPERATIONS`.
     """
 
     _supported_feature_types = [FeatureType.MACHINES, FeatureType.JOBS]

job_shop_lib/dispatching/rules/_dispatching_rule_solver.py

@@ -1,12 +1,14 @@
 """Home of the `DispatchingRuleSolver` class."""
 
-from collections.abc import Callable
+from collections.abc import Callable, Iterable
 
 from job_shop_lib import JobShopInstance, Schedule, Operation, BaseSolver
 from job_shop_lib.dispatching import (
     ready_operations_filter_factory,
     Dispatcher,
     ReadyOperationsFilterType,
+    ReadyOperationsFilter,
+    create_composite_operation_filter,
 )
 from job_shop_lib.dispatching.rules import (
     dispatching_rule_factory,
@@ -30,6 +32,35 @@ class DispatchingRuleSolver(BaseSolver):
         pruning_function:
             The pruning function to use. It is used to initialize the
             dispatcher object internally when calling the solve method.
+
+    Args:
+        dispatching_rule:
+            The dispatching rule to use. It can be a string with the name
+            of the dispatching rule, a class`DispatchingRuleType` enum member,
+            or a callable that takes a dispatcher and returns the operation to
+            be dispatched next.
+        machine_chooser:
+            The machine chooser to use. It can be a string with the name
+            of the machine chooser, a :class:`MachineChooserType` member, or a
+            callable that takes a dispatcher and an operation and returns
+            the machine id where the operation will be dispatched.
+        ready_operations_filter:
+            The ready operations filter to use. It can be either:
+
+            - a string with the name of the pruning function
+            - a :class`ReadyOperationsFilterType` enum member.
+            - a callable that takes a dispatcher and a list of operations
+              and returns a list of operations that should be considered
+              for dispatching,
+            - a list with names or actual ready operations filters to be used.
+              If a list is provided, a composite filter will be created
+              using the specified filters.
+    
+    .. seealso::
+        - :func:`job_shop_lib.dispatching.rules.dispatching_rule_factory`
+        - :func:`job_shop_lib.dispatching.rules.machine_chooser_factory`
+        - :func:`~job_shop_lib.dispatching.ready_operations_filter_factory`
+        - :func:`~job_shop_lib.dispatching.create_composite_operation_filter`
     """
 
     def __init__(
@@ -40,45 +71,33 @@ class DispatchingRuleSolver(BaseSolver):
         machine_chooser: (
             str | Callable[[Dispatcher, Operation], int]
         ) = MachineChooserType.FIRST,
-        pruning_function: (
-            str
-            | Callable[[Dispatcher, list[Operation]], list[Operation]]
+        ready_operations_filter: (
+            Iterable[ReadyOperationsFilter | str | ReadyOperationsFilterType]
+            | str
+            | ReadyOperationsFilterType
+            | ReadyOperationsFilter
             | None
-        ) = ReadyOperationsFilterType.DOMINATED_OPERATIONS,
+        ) = (
+            ReadyOperationsFilterType.DOMINATED_OPERATIONS,
+            ReadyOperationsFilterType.NON_IDLE_MACHINES,
+        ),
     ):
-        """Initializes the solver with the given dispatching rule, machine
-        chooser and pruning function.
-
-        Args:
-            dispatching_rule:
-                The dispatching rule to use. It can be a string with the name
-                of the dispatching rule, a DispatchingRule enum member, or a
-                callable that takes a dispatcher and returns the operation to
-                be dispatched next.
-            machine_chooser:
-                The machine chooser to use. It can be a string with the name
-                of the machine chooser, a MachineChooser enum member, or a
-                callable that takes a dispatcher and an operation and returns
-                the machine id where the operation will be dispatched.
-            pruning_function:
-                The pruning function to use. It can be a string with the name
-                of the pruning function, a PruningFunction enum member, or a
-                callable that takes a dispatcher and a list of operations and
-                returns a list of operations that should be considered for
-                dispatching.
-        """
         if isinstance(dispatching_rule, str):
             dispatching_rule = dispatching_rule_factory(dispatching_rule)
         if isinstance(machine_chooser, str):
             machine_chooser = machine_chooser_factory(machine_chooser)
-        if isinstance(pruning_function, str):
-            pruning_function = ready_operations_filter_factory(
-                pruning_function
+        if isinstance(ready_operations_filter, str):
+            ready_operations_filter = ready_operations_filter_factory(
+                ready_operations_filter
+            )
+        if isinstance(ready_operations_filter, Iterable):
+            ready_operations_filter = create_composite_operation_filter(
+                ready_operations_filter
             )
 
         self.dispatching_rule = dispatching_rule
         self.machine_chooser = machine_chooser
-        self.pruning_function = pruning_function
+        self.ready_operations_filter = ready_operations_filter
 
     def solve(
         self, instance: JobShopInstance, dispatcher: Dispatcher | None = None
@@ -87,7 +106,7 @@ class DispatchingRuleSolver(BaseSolver):
         dispatching rule algorithm."""
         if dispatcher is None:
             dispatcher = Dispatcher(
-                instance, ready_operations_filter=self.pruning_function
+                instance, ready_operations_filter=self.ready_operations_filter
             )
         while not dispatcher.schedule.is_complete():
             self.step(dispatcher)
@@ -110,19 +129,23 @@ class DispatchingRuleSolver(BaseSolver):
 if __name__ == "__main__":
     import time
     import cProfile
-    import pstats
-    from io import StringIO
-    from job_shop_lib.benchmarking import load_benchmark_instance
+    # import pstats
+    # from io import StringIO
+    from job_shop_lib.benchmarking import (
+        # load_benchmark_instance,
+        load_all_benchmark_instances,
+    )
 
     # from job_shop_lib.dispatching.rules._dispatching_rules_functions import (
     #     most_work_remaining_rule_2,
     # )
 
-    ta_instances = [
-        load_benchmark_instance(f"ta{i:02d}") for i in range(1, 81)
-    ]
+    # ta_instances = [
+    #     load_benchmark_instance(f"ta{i:02d}") for i in range(1, 81)
+    # ]
+    ta_instances = load_all_benchmark_instances().values()
     solver = DispatchingRuleSolver(
-        dispatching_rule="most_work_remaining", pruning_function=None
+        dispatching_rule="most_work_remaining", ready_operations_filter=None
     )
 
     start = time.perf_counter()
@@ -131,10 +154,10 @@ if __name__ == "__main__":
     profiler = cProfile.Profile()
 
     # Run the code under profiling
-    profiler.enable()
+    # profiler.enable()
     for instance_ in ta_instances:
         solver.solve(instance_)
-    profiler.disable()
+    # profiler.disable()
 
     end = time.perf_counter()
 
@@ -142,7 +165,7 @@ if __name__ == "__main__":
     print(f"Elapsed time: {end - start:.2f} seconds.")
 
     # Print profiling results
-    s = StringIO()
-    ps = pstats.Stats(profiler, stream=s).sort_stats("cumulative")
-    profiler.print_stats("cumtime")  # Print top 20 time-consuming functions
+    # s = StringIO()
+    # ps = pstats.Stats(profiler, stream=s).sort_stats("cumulative")
+    # profiler.print_stats("cumtime")  # Print top 20 time-consuming functions
     # print(s.getvalue())