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

job_shop_lib/_operation.py

@@ -23,30 +23,34 @@ class Operation:
         necessary to multiply all durations by a sufficiently large integer so
         that every duration is an integer.
 
-    Attributes:
-        machines: A list of machine ids that can perform the operation.
-        duration: The time it takes to perform the operation.
+    Args:
+        machines:
+            A list of machine ids that can perform the operation. If
+            only one machine can perform the operation, it can be passed as
+            an integer.
+        duration:
+            The time it takes to perform the operation.
     """
 
-    __slots__ = (
-        "machines",
-        "duration",
-        "job_id",
-        "position_in_job",
-        "operation_id",
-    )
+    __slots__ = {
+        "machines": (
+            "A list of machine ids that can perform the operation. If "
+            "only one machine can perform the operation, it can be passed as "
+            "an integer."
+        ),
+        "duration": (
+            "The time it takes to perform the operation. Often referred"
+            " to as the processing time."
+        ),
+        "job_id": "The id of the job the operation belongs to.",
+        "position_in_job": "The index of the operation in the job.",
+        "operation_id": (
+            "The id of the operation. This is unique within a "
+            ":class:`JobShopInstance`."
+        ),
+    }
 
     def __init__(self, machines: int | list[int], duration: int):
-        """Initializes the object with the given machines and duration.
-
-        Args:
-            machines:
-                A list of machine ids that can perform the operation. If
-                only one machine can perform the operation, it can be passed as
-                an integer.
-            duration:
-                The time it takes to perform the operation.
-        """
         self.machines = [machines] if isinstance(machines, int) else machines
         self.duration = duration
 

job_shop_lib/_schedule.py

@@ -25,21 +25,22 @@ class Schedule:
         is_complete
         add
         reset
-
-    Attributes:
-        instance:
-            The :class:`JobShopInstance` object that the schedule is for.
-        metadata:
-            A dictionary with additional information about the schedule. It
-            can be used to store information about the algorithm that generated
-            the schedule, for example.
     """
 
-    __slots__ = (
-        "instance",
-        "_schedule",
-        "metadata",
-    )
+    __slots__ = {
+        "instance": (
+            "The :class:`JobShopInstance` object that the schedule is for."
+        ),
+        "_schedule": (
+            "A list of lists of :class:`ScheduledOperation` objects. "
+            "Each list represents the order of operations on a machine."
+        ),
+        "metadata": (
+            "A dictionary with additional information about the "
+            "schedule. It can be used to store information about the "
+            "algorithm that generated the schedule, for example."
+        ),
+    }
 
     def __init__(
         self,

job_shop_lib/_scheduled_operation.py

@@ -5,17 +5,15 @@ from job_shop_lib.exceptions import ValidationError
 
 
 class ScheduledOperation:
-    """Data structure to store a scheduled operation.
-
-    Attributes:
-        operation:
-            The :class:`Operation` object that is scheduled.
-        start_time:
-            The time at which the operation is scheduled to start.
-
-    """
-
-    __slots__ = ("operation", "start_time", "_machine_id")
+    """Data structure to store a scheduled operation."""
+
+    __slots__ = {
+        "operation": "The :class:`Operation` object that is scheduled.",
+        "start_time": "The time at which the operation is scheduled to start.",
+        "_machine_id": (
+            "The id of the machine on which the operation is scheduled."
+        ),
+    }
 
     def __init__(self, operation: Operation, start_time: int, machine_id: int):
         """Initializes a new instance of the :class:`ScheduledOperation` class.

job_shop_lib/constraint_programming/_ortools_solver.py

@@ -22,22 +22,32 @@ class ORToolsSolver(BaseSolver):
     <https://developers.google.com/optimization/cp/cp_solver>`_ solver.
 
     Attributes:
-        log_search_progress (``bool``):
+        log_search_progress (bool):
             Whether to log the search progress to the console.
-        max_time_in_seconds (``float | None``):
+        max_time_in_seconds (float | None):
             The maximum time in seconds to allow the solver to search for
             a solution. If no solution is found within this time, a
             :class:`~job_shop_lib.exceptions.NoSolutionFoundError` is
             raised. If ``None``, the solver will run until an optimal
             solution is found.
-        model (``cp_model.CpModel``):
+        model (cp_model.CpModel):
             The `OR-Tools' CP-SAT model
             <https://developers.google.com/optimization/reference/python/sat/
             python/cp_model#cp_model.CpModel>`_.
-        solver (``cp_model.CpSolver``):
+        solver (cp_model.CpSolver):
             The `OR-Tools' CP-SAT solver
             <https://developers.google.com/optimization/reference/python/sat/
             python/cp_model#cp_model.CpSolver>`_.
+
+    Args:
+        max_time_in_seconds:
+            The maximum time in seconds to allow the solver to search for
+            a solution. If no solution is found within this time, a
+            :class:`~job_shop_lib.exceptions.NoSolutionFoundError` is
+            raised. If ``None``, the solver will run until an optimal
+            solution is found.
+        log_search_progress:
+            Whether to log the search progress to the console.
     """
 
     def __init__(
@@ -45,18 +55,6 @@ class ORToolsSolver(BaseSolver):
         max_time_in_seconds: float | None = None,
         log_search_progress: bool = False,
     ):
-        """Initializes the solver.
-
-        Args:
-            max_time_in_seconds:
-                The maximum time in seconds to allow the solver to search for
-                a solution. If no solution is found within this time, a
-                :class:`~job_shop_lib.exceptions.NoSolutionFoundError` is
-                raised. If ``None``, the solver will run until an optimal
-                solution is found.
-            log_search_progress:
-                Whether to log the search progress to the console.
-        """
         self.log_search_progress = log_search_progress
         self.max_time_in_seconds = max_time_in_seconds
 
@@ -66,6 +64,23 @@ class ORToolsSolver(BaseSolver):
         self._operations_start: dict[Operation, tuple[IntVar, IntVar]] = {}
 
     def __call__(self, instance: JobShopInstance) -> Schedule:
+        """Equivalent to calling the :meth:`~ORToolsSolver.solve` method.
+
+        This method is necessary because, in JobShopLib, solvers are defined
+        as callables that receive an instance and return a schedule.
+
+        Args:
+            instance: The job shop instance to be solved.
+
+        Returns:
+            The best schedule found by the solver.
+            Its metadata contains the following information:
+
+            * status (``str``): ``"optimal"`` or ``"feasible"``
+            * elapsed_time (``float``): The time taken to solve the problem
+            * makespan (``int``): The total duration of the schedule
+            * solved_by (``str``): ``"ORToolsSolver"``
+        """
         # Re-defined here since we already add metadata to the schedule in
         # the solve method.
         return self.solve(instance)

job_shop_lib/dispatching/feature_observers/__init__.py

@@ -1,5 +1,37 @@
-"""Contains FeatureObserver classes for observing features of the
-dispatcher."""
+"""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

job_shop_lib/dispatching/feature_observers/_composite_feature_observer.py

@@ -24,19 +24,54 @@ from job_shop_lib.dispatching.feature_observers import (
 
 class CompositeFeatureObserver(FeatureObserver):
     """Aggregates features from other FeatureObserver instances subscribed to
-    the same `Dispatcher` by concatenating their feature matrices along the
-    first axis (horizontal concatenation).
-
-    Attributes:
+    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:
-            List of `FeatureObserver` instances to aggregate features from.
-        column_names:
-            Dictionary mapping `FeatureType` to a list of column names for the
-            corresponding feature matrix. Column names are generated based on
-            the class name of the `FeatureObserver` instance that produced the
-            feature.
+            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,
@@ -140,7 +175,8 @@ class CompositeFeatureObserver(FeatureObserver):
 
 
 if __name__ == "__main__":
-    from cProfile import Profile
+    # from cProfile import Profile
+    import time
     from job_shop_lib.benchmarking import load_benchmark_instance
     from job_shop_lib.dispatching.rules import DispatchingRuleSolver
     from job_shop_lib.dispatching.feature_observers import (
@@ -164,6 +200,10 @@ if __name__ == "__main__":
         dispatcher_, feature_observers=feature_observers_
     )
     solver = DispatchingRuleSolver(dispatching_rule="random")
-    profiler = Profile()
-    profiler.runcall(solver.solve, dispatcher_.instance, dispatcher_)
-    profiler.print_stats("cumtime")
+    # 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

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