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

job_shop_lib/dispatching/rules/_dispatching_rule_solver.py

@@ -0,0 +1,201 @@
+"""Home of the `DispatchingRuleSolver` class."""
+
+from typing import Optional, Union
+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,
+    machine_chooser_factory,
+    DispatchingRuleType,
+    MachineChooserType,
+)
+
+
+class DispatchingRuleSolver(BaseSolver):
+    """Solves a job shop instance using a dispatching rule.
+
+    Attributes:
+        dispatching_rule:
+            The dispatching rule to use. It is a callable that takes a
+            dispatcher and returns the operation to be dispatched next.
+        machine_chooser:
+            Used to choose the machine where the operation will be dispatched
+            to. It is only used if the operation can be dispatched to multiple
+            machines.
+        ready_operations_filter:
+            The ready operations filter 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` 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__(
+        self,
+        dispatching_rule: Union[
+            str, Callable[[Dispatcher], Operation]
+        ] = DispatchingRuleType.MOST_WORK_REMAINING,
+        machine_chooser: Union[
+            str, Callable[[Dispatcher, Operation], int]
+        ] = MachineChooserType.FIRST,
+        ready_operations_filter: Optional[
+            Union[
+                Iterable[
+                    Union[
+                        ReadyOperationsFilter, str, ReadyOperationsFilterType
+                    ]
+                ],
+                str,
+                ReadyOperationsFilterType,
+                ReadyOperationsFilter,
+            ]
+        ] = (
+            ReadyOperationsFilterType.DOMINATED_OPERATIONS,
+            ReadyOperationsFilterType.NON_IMMEDIATE_OPERATIONS,
+        ),
+    ):
+        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(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.ready_operations_filter = ready_operations_filter
+
+    def solve(
+        self,
+        instance: JobShopInstance,
+        dispatcher: Optional[Dispatcher] = None,
+    ) -> Schedule:
+        """Solves the instance using the dispatching rule and machine chooser
+        algorithms.
+
+        Args:
+            instance:
+                The job shop instance to be solved.
+            dispatcher:
+                The dispatcher object that will be used to dispatch the
+                operations. If not provided, a new dispatcher will be created
+                using the ready operations filter provided in the constructor.
+
+        Returns:
+            The schedule obtained after solving the instance.
+
+        .. tip::
+            Another way to use the solver is by calling it as a function. This
+            will call the ``solve`` method internally and will add metadata to
+            the schedule. For example:
+
+            .. code-block:: python
+
+                solver = DispatchingRuleSolver()
+                schedule = solver(instance)
+        """
+        if dispatcher is None:
+            dispatcher = Dispatcher(
+                instance, ready_operations_filter=self.ready_operations_filter
+            )
+        while not dispatcher.schedule.is_complete():
+            self.step(dispatcher)
+
+        return dispatcher.schedule
+
+    def step(self, dispatcher: Dispatcher) -> None:
+        """Executes one step of the dispatching rule algorithm.
+
+        Args:
+            dispatcher:
+                The dispatcher object that will be used to dispatch the
+                operations.
+        """
+        selected_operation = self.dispatching_rule(dispatcher)
+        machine_id = self.machine_chooser(dispatcher, selected_operation)
+        dispatcher.dispatch(selected_operation, machine_id)
+
+
+if __name__ == "__main__":
+    import time
+    import cProfile
+    # 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_all_benchmark_instances().values()
+    solver = DispatchingRuleSolver(
+        dispatching_rule="most_work_remaining", ready_operations_filter=None
+    )
+
+    start = time.perf_counter()
+
+    # Create a Profile object
+    profiler = cProfile.Profile()
+
+    # Run the code under profiling
+    # profiler.enable()
+    for instance_ in ta_instances:
+        solver.solve(instance_)
+    # profiler.disable()
+
+    end = time.perf_counter()
+
+    # Print elapsed time
+    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
+    # print(s.getvalue())

job_shop_lib/dispatching/{dispatching_rules.py → rules/_dispatching_rules_functions.py}

@@ -6,11 +6,17 @@ which operations are selected for execution based on certain criteria such as
 shortest processing time, first come first served, etc.
 """
 
-from typing import Callable
+from typing import List, Optional
+from collections.abc import Callable, Sequence
 import random
 
 from job_shop_lib import Operation
-from job_shop_lib.dispatching import Dispatcher
+from job_shop_lib.dispatching import Dispatcher, DispatcherObserver
+from job_shop_lib.dispatching.feature_observers import (
+    DurationObserver,
+    FeatureType,
+    IsReadyObserver,
+)
 
 
 def shortest_processing_time_rule(dispatcher: Dispatcher) -> Operation:
@@ -32,7 +38,7 @@ def first_come_first_served_rule(dispatcher: Dispatcher) -> Operation:
 def most_work_remaining_rule(dispatcher: Dispatcher) -> Operation:
     """Dispatches the operation which job has the most remaining work."""
     job_remaining_work = [0] * dispatcher.instance.num_jobs
-    for operation in dispatcher.uncompleted_operations():
+    for operation in dispatcher.unscheduled_operations():
         job_remaining_work[operation.job_id] += operation.duration
 
     return max(
@@ -59,7 +65,7 @@ def random_operation_rule(dispatcher: Dispatcher) -> Operation:
 
 
 def score_based_rule(
-    score_function: Callable[[Dispatcher], list[int]]
+    score_function: Callable[[Dispatcher], Sequence[float]]
 ) -> Callable[[Dispatcher], Operation]:
     """Creates a dispatching rule based on a scoring function.
 
@@ -83,7 +89,7 @@ def score_based_rule(
 
 
 def score_based_rule_with_tie_breaker(
-    score_functions: list[Callable[[Dispatcher], list[int]]],
+    score_functions: List[Callable[[Dispatcher], Sequence[int]]],
 ) -> Callable[[Dispatcher], Operation]:
     """Creates a dispatching rule based on multiple scoring functions.
 
@@ -117,7 +123,7 @@ def score_based_rule_with_tie_breaker(
 # -----------------
 
 
-def shortest_processing_time_score(dispatcher: Dispatcher) -> list[int]:
+def shortest_processing_time_score(dispatcher: Dispatcher) -> List[int]:
     """Scores each job based on the duration of the next operation."""
     num_jobs = dispatcher.instance.num_jobs
     scores = [0] * num_jobs
@@ -126,7 +132,7 @@ def shortest_processing_time_score(dispatcher: Dispatcher) -> list[int]:
     return scores
 
 
-def first_come_first_served_score(dispatcher: Dispatcher) -> list[int]:
+def first_come_first_served_score(dispatcher: Dispatcher) -> List[int]:
     """Scores each job based on the position of the next operation."""
     num_jobs = dispatcher.instance.num_jobs
     scores = [0] * num_jobs
@@ -135,16 +141,64 @@ def first_come_first_served_score(dispatcher: Dispatcher) -> list[int]:
     return scores
 
 
-def most_work_remaining_score(dispatcher: Dispatcher) -> list[int]:
-    """Scores each job based on the remaining work in the job."""
-    num_jobs = dispatcher.instance.num_jobs
-    scores = [0] * num_jobs
-    for operation in dispatcher.uncompleted_operations():
-        scores[operation.job_id] += operation.duration
-    return scores
+class MostWorkRemainingScorer:  # pylint: disable=too-few-public-methods
+    """Scores each job based on the remaining work in the job.
+
+    This class is conceptually a function: it can be called with a
+    :class:`~job_shop_lib.dispatching.Dispatcher` instance as input, and it
+    returns a list of scores for each job. The reason for using a class instead
+    of a function is to cache the observers that are created for each
+    dispatcher instance. This way, the observers do not have to be retrieved
+    every time the function is called.
+
+    """
+
+    def __init__(self) -> None:
+        self._duration_observer: Optional[DurationObserver] = None
+        self._is_ready_observer: Optional[IsReadyObserver] = None
+        self._current_dispatcher: Optional[Dispatcher] = None
+
+    def __call__(self, dispatcher: Dispatcher) -> Sequence[int]:
+        """Scores each job based on the remaining work in the job."""
+
+        if self._current_dispatcher is not dispatcher:
+            self._duration_observer = None
+            self._is_ready_observer = None
+            self._current_dispatcher = dispatcher
+
+        def has_job_feature(observer: DispatcherObserver) -> bool:
+            if not isinstance(observer, DurationObserver):
+                return False
+            return FeatureType.JOBS in observer.features
+
+        if self._duration_observer is None:
+            self._duration_observer = dispatcher.create_or_get_observer(
+                DurationObserver,
+                condition=has_job_feature,
+                feature_types=FeatureType.JOBS,
+            )
+        if self._is_ready_observer is None:
+            self._is_ready_observer = dispatcher.create_or_get_observer(
+                IsReadyObserver,
+                condition=has_job_feature,
+                feature_types=FeatureType.JOBS,
+            )
+
+        work_remaining = self._duration_observer.features[
+            FeatureType.JOBS
+        ].copy()
+        is_ready = self._is_ready_observer.features[FeatureType.JOBS]
+        work_remaining[~is_ready.astype(bool)] = 0
+
+        return work_remaining.ravel()  # type: ignore[return-value]
+
+
+observer_based_most_work_remaining_rule = score_based_rule(
+    MostWorkRemainingScorer()
+)
 
 
-def most_operations_remaining_score(dispatcher: Dispatcher) -> list[int]:
+def most_operations_remaining_score(dispatcher: Dispatcher) -> List[int]:
     """Scores each job based on the remaining operations in the job."""
     num_jobs = dispatcher.instance.num_jobs
     scores = [0] * num_jobs
@@ -153,7 +207,7 @@ def most_operations_remaining_score(dispatcher: Dispatcher) -> list[int]:
     return scores
 
 
-def random_score(dispatcher: Dispatcher) -> list[int]:
+def random_score(dispatcher: Dispatcher) -> List[int]:
     """Scores each job randomly."""
     return [
         random.randint(0, 100) for _ in range(dispatcher.instance.num_jobs)

job_shop_lib/dispatching/rules/_machine_chooser_factory.py

@@ -0,0 +1,71 @@
+"""Contains factory functions for creating dispatching rules, machine choosers,
+and pruning functions for the job shop scheduling problem.
+
+The factory functions create and return the appropriate functions based on the
+specified names or enums.
+"""
+
+from typing import Union, Dict
+from enum import Enum
+from collections.abc import Callable
+import random
+
+from job_shop_lib import Operation
+from job_shop_lib.exceptions import ValidationError
+from job_shop_lib.dispatching import Dispatcher
+
+
+class MachineChooserType(str, Enum):
+    """Enumeration of machine chooser strategies for the job shop scheduling"""
+
+    FIRST = "first"
+    RANDOM = "random"
+
+
+MachineChooser = Callable[[Dispatcher, Operation], int]
+
+
+def machine_chooser_factory(
+    machine_chooser: Union[str, MachineChooser],
+) -> MachineChooser:
+    """Creates and returns a machine chooser function based on the specified
+    machine chooser strategy name.
+
+    The machine chooser function determines which machine an operation should
+    be assigned to for execution. The selection can be based on different
+    strategies such as choosing the first available machine or selecting a
+    machine randomly.
+
+    Args:
+        machine_chooser: The name of the machine chooser strategy to be
+            used. Supported values are 'first' and 'random'.
+
+    Returns:
+        A function that takes a :class:`~job_shop_lib.dispatching.Dispatcher`
+        and an :class:`~job_shop_lib.Operation` as input
+        and returns the index of the selected machine based on the specified
+        machine chooser strategy.
+
+    Raises:
+        ValidationError:
+            If the ``machine_chooser`` argument is not recognized or
+            is not supported.
+    """
+    machine_choosers: Dict[str, Callable[[Dispatcher, Operation], int]] = {
+        MachineChooserType.FIRST: lambda _, operation: operation.machines[0],
+        MachineChooserType.RANDOM: lambda _, operation: random.choice(
+            operation.machines
+        ),
+    }
+
+    if callable(machine_chooser):
+        return machine_chooser
+
+    machine_chooser = machine_chooser.lower()
+    if machine_chooser not in machine_choosers:
+        raise ValidationError(
+            f"Machine chooser {machine_chooser} not recognized. Available "
+            f"machine choosers: {', '.join(machine_choosers)}."
+        )
+
+    return machine_choosers[machine_chooser]

job_shop_lib/dispatching/rules/_utils.py

@@ -0,0 +1,128 @@
+"""Utility functions."""
+
+from typing import Union, List
+import time
+from collections.abc import Callable
+import pandas as pd
+from job_shop_lib import JobShopInstance, Operation
+from job_shop_lib.exceptions import JobShopLibError
+from job_shop_lib.dispatching.rules import DispatchingRuleSolver
+from job_shop_lib.dispatching import Dispatcher
+
+
+def benchmark_dispatching_rules(
+    dispatching_rules: Union[
+        List[Union[str, Callable[[Dispatcher], Operation]]],
+        List[str],
+        List[Callable[[Dispatcher], Operation]]
+    ],
+    instances: List[JobShopInstance],
+) -> pd.DataFrame:
+    """Benchmark multiple dispatching rules on multiple JobShopInstances.
+
+    This function applies each provided dispatching rule to each given
+    :class:`JobShopInstance`, measuring the time taken to solve and the
+    makespan of the resulting schedule. It returns a DataFrame summarizing
+    the results.
+
+    Args:
+        dispatching_rules:
+            List of dispatching rules. Each rule can be
+            either a string (name of a built-in rule) or a callable
+            (custom rule function).
+        instances:
+            List of :class:`JobShopInstance` objects to be solved.
+
+    Returns:
+        A pandas DataFrame with columns:
+            - instance: Name of the :class:`JobShopInstance`.
+            - rule: Name of the dispatching rule used.
+            - time: Time taken to solve the instance (in seconds).
+            - makespan: Makespan of the resulting schedule.
+
+    Raises:
+        Any exception that might occur during the solving process is caught
+        and logged, with None values recorded for time and makespan.
+
+    Example:
+        >>> from job_shop_lib.benchmarking import load_benchmark_instance
+        >>> instances = [load_benchmark_instance(f"ta{i:02d}")
+        ... for i in range(1, 3)]
+        >>> rules = ["most_work_remaining", "shortest_processing_time"]
+        >>> df = benchmark_dispatching_rules(rules, instances)
+        >>> print(df)
+          instance                        rule      time  makespan
+        0     ta01    shortest_processing_time  0.006492      3439
+        1     ta01    most_work_remaining_rule  0.012608      1583
+        2     ta02    shortest_processing_time  0.006240      2568
+        3     ta02    most_work_remaining_rule  0.012315      1630
+
+    Note:
+        - The function handles errors gracefully, allowing the benchmarking
+          process to continue even if solving a particular instance fails.
+        - For custom rule functions, the function name is used in the
+          'rule' column of the output DataFrame.
+    """
+    results = []
+
+    for instance in instances:
+        for rule in dispatching_rules:
+            solver = DispatchingRuleSolver(dispatching_rule=rule)
+
+            start_time = time.perf_counter()
+            try:
+                schedule = solver.solve(instance)
+                solve_time = time.perf_counter() - start_time
+                makespan = schedule.makespan()
+
+                results.append(
+                    {
+                        "instance": instance.name,
+                        "rule": (
+                            rule if isinstance(rule, str) else rule.__name__
+                        ),
+                        "time": solve_time,
+                        "makespan": makespan,
+                    }
+                )
+            except JobShopLibError as e:
+                print(f"Error solving {instance.name} with {rule}: {str(e)}")
+                results.append(
+                    {
+                        "instance": instance.name,
+                        "rule": (
+                            rule if isinstance(rule, str) else rule.__name__
+                        ),
+                        "time": None,
+                        "makespan": None,
+                    }
+                )
+
+    return pd.DataFrame(results)
+
+
+# Example usage:
+if __name__ == "__main__":
+    from job_shop_lib.benchmarking import load_benchmark_instance
+    from job_shop_lib.dispatching.rules._dispatching_rules_functions import (
+        most_work_remaining_rule,
+    )
+
+    # Load instances
+    instances_ = [load_benchmark_instance(f"ta{i:02d}") for i in range(1, 3)]
+
+    # Define rules
+    rules_: List[str | Callable[[Dispatcher], Operation]] = [
+        "most_work_remaining",
+        "shortest_processing_time",
+        most_work_remaining_rule,
+    ]
+
+    # Run benchmark
+    df = benchmark_dispatching_rules(rules_, instances_)
+
+    # Display results
+    print(df)
+
+    # Group results by rule and compute average makespan and time
+    print(df.groupby("rule")[["time", "makespan"]].mean())

job_shop_lib/exceptions.py

@@ -24,3 +24,21 @@ class NoSolutionFoundError(JobShopLibError):
     TypeError, which may indicate a bug in the code or an invalid
     input, rather than a failure to find a solution.
     """
+
+
+class ValidationError(JobShopLibError):
+    """Exception raised when a validation check fails.
+
+    This exception is raised when a validation check fails, indicating
+    that the input data is invalid or does not meet the requirements of
+    the function or class that is performing the validation.
+
+    It is useful to distinguish this exception from other exceptions
+    that may be raised by a function or class, such as a ValueError or
+    a TypeError, which may indicate a bug in the code or an invalid
+    input, rather than a validation failure.
+    """
+
+
+class UninitializedAttributeError(JobShopLibError):
+    """Exception raised when an attribute is accessed before initialization."""

job_shop_lib/generation/__init__.py

@@ -0,0 +1,19 @@
+"""Package for generating job shop instances."""
+
+from job_shop_lib.generation._utils import (
+    generate_duration_matrix,
+    generate_machine_matrix_with_recirculation,
+    generate_machine_matrix_without_recirculation,
+)
+from job_shop_lib.generation._instance_generator import InstanceGenerator
+from job_shop_lib.generation._general_instance_generator import (
+    GeneralInstanceGenerator,
+)
+
+__all__ = [
+    "InstanceGenerator",
+    "GeneralInstanceGenerator",
+    "generate_duration_matrix",
+    "generate_machine_matrix_with_recirculation",
+    "generate_machine_matrix_without_recirculation",
+]