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

job_shop_lib/_job_shop_instance.py

@@ -20,15 +20,27 @@ class JobShopInstance:
     computations.
 
     Attributes:
-        jobs:
+        jobs (list[list[Operation]]):
             A list of lists of operations. Each list of operations represents
             a job, and the operations are ordered by their position in the job.
             The `job_id`, `position_in_job`, and `operation_id` attributes of
             the operations are set when the instance is created.
-        name:
+        name (str):
             A string with the name of the instance.
-        metadata:
+        metadata (dict[str, Any]):
             A dictionary with additional information about the instance.
+
+    Args:
+        jobs:
+            A list of lists of operations. Each list of operations
+            represents a job, and the operations are ordered by their
+            position in the job. The `job_id`, `position_in_job`, and
+            `operation_id` attributes of the operations are set when the
+            instance is created.
+        name:
+            A string with the name of the instance.
+        **metadata:
+            Additional information about the instance.
     """
 
     def __init__(
@@ -37,24 +49,10 @@ class JobShopInstance:
         name: str = "JobShopInstance",
         **metadata: Any,
     ):
-        """Initializes the instance based on a list of lists of operations.
-
-        Args:
-            jobs:
-                A list of lists of operations. Each list of operations
-                represents a job, and the operations are ordered by their
-                position in the job. The `job_id`, `position_in_job`, and
-                `operation_id` attributes of the operations are set when the
-                instance is created.
-            name:
-                A string with the name of the instance.
-            **metadata:
-                Additional information about the instance.
-        """
-        self.jobs = jobs
+        self.jobs: list[list[Operation]] = jobs
         self.set_operation_attributes()
-        self.name = name
-        self.metadata = metadata
+        self.name: str = name
+        self.metadata: dict[str, Any] = metadata
 
     def set_operation_attributes(self):
         """Sets the job_id and position of each operation."""

job_shop_lib/_operation.py

@@ -23,32 +23,38 @@ 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
+        self.machines: list[int] = (
+            [machines] if isinstance(machines, int) else machines
+        )
+        self.duration: int = duration
 
         # Defined outside the class by the JobShopInstance class:
         self.job_id: int = -1
@@ -60,8 +66,8 @@ class Operation:
         """Returns the id of the machine associated with the operation.
 
         Raises:
-            UninitializedAttributeError: If the operation has multiple machines
-            in its list.
+            UninitializedAttributeError:
+                If the operation has multiple machines in its list.
         """
         if len(self.machines) > 1:
             raise UninitializedAttributeError(

job_shop_lib/_schedule.py

@@ -25,27 +25,28 @@ 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,
         instance: JobShopInstance,
         schedule: list[list[ScheduledOperation]] | None = None,
-        **metadata,
+        **metadata: Any,
     ):
         """Initializes the object with the given instance and schedule.
 
@@ -64,9 +65,9 @@ class Schedule:
 
         Schedule.check_schedule(schedule)
 
-        self.instance = instance
+        self.instance: JobShopInstance = instance
         self._schedule = schedule
-        self.metadata = metadata
+        self.metadata: dict[str, Any] = metadata
 
     def __repr__(self) -> str:
         return str(self.schedule)

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.
+    """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")
+    __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.
@@ -33,8 +31,8 @@ class ScheduledOperation:
                 If the given machine_id is not in the list of valid machines
                 for the operation.
         """
-        self.operation = operation
-        self.start_time = start_time
+        self.operation: Operation = operation
+        self.start_time: int = start_time
         self._machine_id = machine_id
         self.machine_id = machine_id  # Validate machine_id
 

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/__init__.py

@@ -32,6 +32,8 @@ from ._ready_operation_filters import (
     filter_dominated_operations,
     filter_non_immediate_machines,
     ReadyOperationsFilter,
+    filter_non_idle_machines,
+    filter_non_immediate_operations,
 )
 from ._dispatcher_observer_config import DispatcherObserverConfig
 from ._factories import (
@@ -53,4 +55,6 @@ __all__ = [
     "DispatcherObserverConfig",
     "UnscheduledOperationsObserver",
     "ReadyOperationsFilter",
+    "filter_non_idle_machines",
+    "filter_non_immediate_operations",
 ]

job_shop_lib/dispatching/_dispatcher.py

@@ -156,26 +156,30 @@ class Dispatcher:
     responsible for scheduling the operations on the machines and keeping
     track of the next available time for each machine and job.
 
-    Attributes:
+    Args:
         instance:
-            The instance of the job shop problem to be scheduled.
-        schedule:
-            The schedule of operations on machines.
+            The instance of the job shop problem to be solved.
         ready_operations_filter:
-            A function that filters out operations that are not ready to be
-            scheduled.
+            A function that filters out operations that are not ready to
+            be scheduled. The function should take the dispatcher and a
+            list of operations as input and return a list of operations
+            that are ready to be scheduled. If ``None``, no filtering is
+            done.
     """
 
-    __slots__ = (
-        "instance",
-        "schedule",
-        "_machine_next_available_time",
-        "_job_next_operation_index",
-        "_job_next_available_time",
-        "ready_operations_filter",
-        "subscribers",
-        "_cache",
-    )
+    __slots__ = {
+        "instance": "The instance of the job shop problem to be scheduled.",
+        "schedule": "The schedule of operations on machines.",
+        "_machine_next_available_time": "",
+        "_job_next_operation_index": "",
+        "_job_next_available_time": "",
+        "ready_operations_filter": (
+            "A function that filters out operations that are not ready to be "
+            "scheduled."
+        ),
+        "subscribers": "A list of observers subscribed to the dispatcher.",
+        "_cache": "A dictionary to cache the results of the cached methods.",
+    }
 
     def __init__(
         self,
@@ -184,18 +188,6 @@ class Dispatcher:
             Callable[[Dispatcher, list[Operation]], list[Operation]] | None
         ) = None,
     ) -> None:
-        """Initializes the object with the given instance.
-
-        Args:
-            instance:
-                The instance of the job shop problem to be solved.
-            ready_operations_filter:
-                A function that filters out operations that are not ready to
-                be scheduled. The function should take the dispatcher and a
-                list of operations as input and return a list of operations
-                that are ready to be scheduled. If ``None``, no filtering is
-                done.
-        """
 
         self.instance = instance
         self.schedule = Schedule(self.instance)
@@ -371,7 +363,7 @@ class Dispatcher:
         The current time is the minimum start time of the available
         operations.
         """
-        available_operations = self.ready_operations()
+        available_operations = self.available_operations()
         current_time = self.min_start_time(available_operations)
         return current_time
 
@@ -387,7 +379,7 @@ class Dispatcher:
         return int(min_start_time)
 
     @_dispatcher_cache
-    def ready_operations(self) -> list[Operation]:
+    def available_operations(self) -> list[Operation]:
         """Returns a list of available operations for processing, optionally
         filtering out operations using the filter function.
 
@@ -443,7 +435,7 @@ class Dispatcher:
     @_dispatcher_cache
     def available_machines(self) -> list[int]:
         """Returns the list of ready machines."""
-        available_operations = self.ready_operations()
+        available_operations = self.available_operations()
         available_machines = set()
         for operation in available_operations:
             available_machines.update(operation.machines)
@@ -452,7 +444,7 @@ class Dispatcher:
     @_dispatcher_cache
     def available_jobs(self) -> list[int]:
         """Returns the list of ready jobs."""
-        available_operations = self.ready_operations()
+        available_operations = self.available_operations()
         available_jobs = set(
             operation.job_id for operation in available_operations
         )

job_shop_lib/dispatching/_factories.py

@@ -13,6 +13,8 @@ from job_shop_lib.dispatching import (
     Dispatcher,
     filter_dominated_operations,
     filter_non_immediate_machines,
+    filter_non_idle_machines,
+    filter_non_immediate_operations,
     ReadyOperationsFilter,
 )
 
@@ -27,6 +29,8 @@ class ReadyOperationsFilterType(str, Enum):
 
     DOMINATED_OPERATIONS = "dominated_operations"
     NON_IMMEDIATE_MACHINES = "non_immediate_machines"
+    NON_IDLE_MACHINES = "non_idle_machines"
+    NON_IMMEDIATE_OPERATIONS = "non_immediate_operations"
 
 
 def create_composite_operation_filter(
@@ -114,6 +118,10 @@ def ready_operations_filter_factory(
         ReadyOperationsFilterType.NON_IMMEDIATE_MACHINES: (
             filter_non_immediate_machines
         ),
+        ReadyOperationsFilterType.NON_IDLE_MACHINES: filter_non_idle_machines,
+        ReadyOperationsFilterType.NON_IMMEDIATE_OPERATIONS: (
+            filter_non_immediate_operations
+        ),
     }
 
     if filter_name not in filtering_strategies:

job_shop_lib/dispatching/_ready_operation_filters.py

@@ -15,6 +15,86 @@ ReadyOperationsFilter = Callable[
 ]
 
 
+def filter_non_idle_machines(
+    dispatcher: Dispatcher, operations: list[Operation]
+) -> list[Operation]:
+    """Filters out all the operations associated with non-idle machines.
+
+    A machine is considered idle if there are no ongoing operations
+    currently scheduled on it. This filter removes operations that are
+    associated with machines that are busy (i.e., have at least one
+    uncompleted operation).
+
+    Utilizes :meth:``Dispatcher.ongoing_operations()`` to determine machine
+    statuses.
+
+    Args:
+        dispatcher: The dispatcher object.
+        operations: The list of operations to filter.
+
+    Returns:
+        The list of operations that are associated with idle machines.
+    """
+    current_time = dispatcher.min_start_time(operations)
+    non_idle_machines = _get_non_idle_machines(dispatcher, current_time)
+
+    # Filter operations to keep those that are associated with at least one
+    # idle machine
+    filtered_operations: list[Operation] = []
+    for operation in operations:
+        if all(
+            machine_id in non_idle_machines
+            for machine_id in operation.machines
+        ):
+            continue
+        filtered_operations.append(operation)
+
+    return filtered_operations
+
+
+def _get_non_idle_machines(
+    dispatcher: Dispatcher, current_time: int
+) -> set[int]:
+    """Returns the set of machine ids that are currently busy (i.e., have at
+    least one uncompleted operation)."""
+
+    non_idle_machines = set()
+    for machine_schedule in dispatcher.schedule.schedule:
+        for scheduled_operation in reversed(machine_schedule):
+            is_completed = scheduled_operation.end_time <= current_time
+            if is_completed:
+                break
+            non_idle_machines.add(scheduled_operation.machine_id)
+
+    return non_idle_machines
+
+
+def filter_non_immediate_operations(
+    dispatcher: Dispatcher, operations: list[Operation]
+) -> list[Operation]:
+    """Filters out all the operations that can't start immediately.
+
+    An operation can start immediately if its earliest start time is the
+    current time.
+
+    The current time is determined by the minimum start time of the
+    operations.
+
+    Args:
+        dispatcher: The dispatcher object.
+        operations: The list of operations to filter.
+    """
+
+    min_start_time = dispatcher.min_start_time(operations)
+    immediate_operations: list[Operation] = []
+    for operation in operations:
+        start_time = dispatcher.earliest_start_time(operation)
+        if start_time == min_start_time:
+            immediate_operations.append(operation)
+
+    return immediate_operations
+
+
 def filter_dominated_operations(
     dispatcher: Dispatcher, operations: list[Operation]
 ) -> list[Operation]:

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}")