job-shop-lib 0.1.0__py3-none-any.whl

job_shop_lib/dispatching/dispatching_rule_solver.py

@@ -0,0 +1,111 @@
+"""Home of the `DispatchingRuleSolver` class."""
+
+from collections.abc import Callable
+
+from job_shop_lib import JobShopInstance, Schedule, Operation, BaseSolver
+from job_shop_lib.dispatching import (
+    dispatching_rule_factory,
+    machine_chooser_factory,
+    pruning_function_factory,
+    DispatchingRule,
+    MachineChooser,
+    Dispatcher,
+    PruningFunction,
+)
+
+
+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.
+        pruning_function:
+            The pruning function to use. It is used to initialize the
+            dispatcher object internally when calling the solve method.
+    """
+
+    def __init__(
+        self,
+        dispatching_rule: (
+            str | Callable[[Dispatcher], Operation]
+        ) = DispatchingRule.MOST_WORK_REMAINING,
+        machine_chooser: (
+            str | Callable[[Dispatcher, Operation], int]
+        ) = MachineChooser.FIRST,
+        pruning_function: (
+            str
+            | Callable[[Dispatcher, list[Operation]], list[Operation]]
+            | None
+        ) = PruningFunction.DOMINATED_OPERATIONS,
+    ):
+        """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 = pruning_function_factory(pruning_function)
+
+        self.dispatching_rule = dispatching_rule
+        self.machine_chooser = machine_chooser
+        self.pruning_function = pruning_function
+
+    def solve(self, instance: JobShopInstance) -> Schedule:
+        """Returns a schedule for the given job shop instance using the
+        dispatching rule algorithm."""
+        dispatcher = Dispatcher(
+            instance, pruning_function=self.pruning_function
+        )
+        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 cProfile
+    from job_shop_lib.benchmarking import load_benchmark_instance
+
+    ta_instances = []
+    for i in range(1, 81):
+        ta_instances.append(load_benchmark_instance(f"ta{i:02d}"))
+    solver = DispatchingRuleSolver(dispatching_rule="most_work_remaining")
+    cProfile.run("for instance in ta_instances: solver.solve(instance)")

job_shop_lib/dispatching/dispatching_rules.py

@@ -0,0 +1,160 @@
+"""Dispatching rules for the job shop scheduling problem.
+
+This module contains functions that implement different dispatching rules for
+the job shop scheduling problem. A dispatching rule determines the order in
+which operations are selected for execution based on certain criteria such as
+shortest processing time, first come first served, etc.
+"""
+
+from typing import Callable
+import random
+
+from job_shop_lib import Operation
+from job_shop_lib.dispatching import Dispatcher
+
+
+def shortest_processing_time_rule(dispatcher: Dispatcher) -> Operation:
+    """Dispatches the operation with the shortest duration."""
+    return min(
+        dispatcher.available_operations(),
+        key=lambda operation: operation.duration,
+    )
+
+
+def first_come_first_served_rule(dispatcher: Dispatcher) -> Operation:
+    """Dispatches the operation with the lowest position in job."""
+    return min(
+        dispatcher.available_operations(),
+        key=lambda operation: operation.position_in_job,
+    )
+
+
+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():
+        job_remaining_work[operation.job_id] += operation.duration
+
+    return max(
+        dispatcher.available_operations(),
+        key=lambda operation: job_remaining_work[operation.job_id],
+    )
+
+
+def most_operations_remaining_rule(dispatcher: Dispatcher) -> Operation:
+    """Dispatches the operation which job has the most remaining operations."""
+    job_remaining_operations = [0] * dispatcher.instance.num_jobs
+    for operation in dispatcher.uncompleted_operations():
+        job_remaining_operations[operation.job_id] += 1
+
+    return max(
+        dispatcher.available_operations(),
+        key=lambda operation: job_remaining_operations[operation.job_id],
+    )
+
+
+def random_operation_rule(dispatcher: Dispatcher) -> Operation:
+    """Dispatches a random operation."""
+    return random.choice(dispatcher.available_operations())
+
+
+def score_based_rule(
+    score_function: Callable[[Dispatcher], list[int]]
+) -> Callable[[Dispatcher], Operation]:
+    """Creates a dispatching rule based on a scoring function.
+
+    Args:
+        score_function: A function that takes a Dispatcher instance as input
+            and returns a list of scores for each job.
+
+    Returns:
+        A dispatching rule function that selects the operation with the highest
+        score based on the specified scoring function.
+    """
+
+    def rule(dispatcher: Dispatcher) -> Operation:
+        scores = score_function(dispatcher)
+        return max(
+            dispatcher.available_operations(),
+            key=lambda operation: scores[operation.job_id],
+        )
+
+    return rule
+
+
+def score_based_rule_with_tie_breaker(
+    score_functions: list[Callable[[Dispatcher], list[int]]],
+) -> Callable[[Dispatcher], Operation]:
+    """Creates a dispatching rule based on multiple scoring functions.
+
+    If there is a tie between two operations based on the first scoring
+    function, the second scoring function is used as a tie breaker. If there is
+    still a tie, the third scoring function is used, and so on.
+
+    Args:
+        score_functions: A list of scoring functions that take a Dispatcher
+            instance as input and return a list of scores for each job.
+    """
+
+    def rule(dispatcher: Dispatcher) -> Operation:
+        candidates = dispatcher.available_operations()
+        for scoring_function in score_functions:
+            scores = scoring_function(dispatcher)
+            best_score = max(scores)
+            candidates = [
+                operation
+                for operation in candidates
+                if scores[operation.job_id] == best_score
+            ]
+            if len(candidates) == 1:
+                return candidates[0]
+        return candidates[0]
+
+    return rule
+
+
+# SCORING FUNCTIONS
+# -----------------
+
+
+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
+    for operation in dispatcher.available_operations():
+        scores[operation.job_id] = -operation.duration
+    return scores
+
+
+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
+    for operation in dispatcher.available_operations():
+        scores[operation.job_id] = operation.operation_id
+    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
+
+
+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
+    for operation in dispatcher.uncompleted_operations():
+        scores[operation.job_id] += 1
+    return scores
+
+
+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/factories.py

@@ -0,0 +1,206 @@
+"""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 enum import Enum
+
+from collections.abc import Callable, Sequence
+import random
+
+from job_shop_lib import Operation
+from job_shop_lib.dispatching import (
+    shortest_processing_time_rule,
+    first_come_first_served_rule,
+    most_work_remaining_rule,
+    most_operations_remaining_rule,
+    random_operation_rule,
+    Dispatcher,
+    prune_dominated_operations,
+    prune_non_immediate_machines,
+    create_composite_pruning_function,
+)
+
+
+class DispatchingRule(str, Enum):
+    """Enumeration of dispatching rules for the job shop scheduling problem."""
+
+    SHORTEST_PROCESSING_TIME = "shortest_processing_time"
+    FIRST_COME_FIRST_SERVED = "first_come_first_served"
+    MOST_WORK_REMAINING = "most_work_remaining"
+    MOST_OPERATIONS_REMAINING = "most_operations_remaining"
+    RANDOM = "random"
+
+
+class MachineChooser(str, Enum):
+    """Enumeration of machine chooser strategies for the job shop scheduling"""
+
+    FIRST = "first"
+    RANDOM = "random"
+
+
+class PruningFunction(str, Enum):
+    """Enumeration of pruning functions.
+
+    A pruning function is used by the `Dispatcher` class to reduce the
+    amount of available operations to choose from.
+    """
+
+    DOMINATED_OPERATIONS = "dominated_operations"
+    NON_IMMEDIATE_MACHINES = "non_immediate_machines"
+
+
+def dispatching_rule_factory(
+    dispatching_rule: str | DispatchingRule,
+) -> Callable[[Dispatcher], Operation]:
+    """Creates and returns a dispatching rule function based on the specified
+    dispatching rule name.
+
+    The dispatching rule function determines the order in which operations are
+    selected for execution based on certain criteria such as shortest
+    processing time, first come first served, etc.
+
+    Args:
+        dispatching_rule: The name of the dispatching rule to be used.
+            Supported values are 'shortest_processing_time',
+            'first_come_first_served', 'most_work_remaining',
+            and 'random'.
+
+    Returns:
+        A function that takes a Dispatcher instance as input and returns an
+        Operation based on the specified dispatching rule.
+
+    Raises:
+        ValueError: If the dispatching_rule argument is not recognized or is
+            not supported.
+    """
+    dispatching_rules = {
+        DispatchingRule.SHORTEST_PROCESSING_TIME: (
+            shortest_processing_time_rule
+        ),
+        DispatchingRule.FIRST_COME_FIRST_SERVED: first_come_first_served_rule,
+        DispatchingRule.MOST_WORK_REMAINING: most_work_remaining_rule,
+        DispatchingRule.MOST_OPERATIONS_REMAINING: (
+            most_operations_remaining_rule
+        ),
+        DispatchingRule.RANDOM: random_operation_rule,
+    }
+
+    dispatching_rule = dispatching_rule.lower()
+    if dispatching_rule not in dispatching_rules:
+        raise ValueError(
+            f"Dispatching rule {dispatching_rule} not recognized. Available "
+            f"dispatching rules: {', '.join(dispatching_rules)}."
+        )
+
+    return dispatching_rules[dispatching_rule]  # type: ignore[index]
+
+
+def machine_chooser_factory(
+    machine_chooser: str,
+) -> Callable[[Dispatcher, Operation], int]:
+    """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 (str): The name of the machine chooser strategy to be
+            used. Supported values are 'first' and 'random'.
+
+    Returns:
+        A function that takes a Dispatcher instance and an Operation as input
+        and returns the index of the selected machine based on the specified
+        machine chooser strategy.
+
+    Raises:
+        ValueError: If the machine_chooser argument is not recognized or is
+            not supported.
+    """
+    machine_choosers: dict[str, Callable[[Dispatcher, Operation], int]] = {
+        MachineChooser.FIRST: lambda _, operation: operation.machines[0],
+        MachineChooser.RANDOM: lambda _, operation: random.choice(
+            operation.machines
+        ),
+    }
+
+    machine_chooser = machine_chooser.lower()
+    if machine_chooser not in machine_choosers:
+        raise ValueError(
+            f"Machine chooser {machine_chooser} not recognized. Available "
+            f"machine choosers: {', '.join(machine_choosers)}."
+        )
+
+    return machine_choosers[machine_chooser]
+
+
+def composite_pruning_function_factory(
+    pruning_function_names: Sequence[str | PruningFunction],
+) -> Callable[[Dispatcher, list[Operation]], list[Operation]]:
+    """Creates and returns a composite pruning function based on the
+    specified list of pruning strategies.
+
+    The composite pruning function filters out operations based on
+    the specified list of pruning strategies.
+
+    Args:
+        pruning_functions:
+            A list of pruning strategies to be used. Supported values are
+            'dominated_operations' and 'non_immediate_machines'.
+
+    Returns:
+        A function that takes a Dispatcher instance and a list of Operation
+        instances as input and returns a list of Operation instances based on
+        the specified list of pruning strategies.
+
+    Raises:
+        ValueError: If any of the pruning strategies in the list are not
+            recognized or are not supported.
+    """
+
+    pruning_functions = [
+        pruning_function_factory(name) for name in pruning_function_names
+    ]
+    return create_composite_pruning_function(pruning_functions)
+
+
+def pruning_function_factory(
+    pruning_function_name: str | PruningFunction,
+) -> Callable[[Dispatcher, list[Operation]], list[Operation]]:
+    """Creates and returns a pruning function based on the specified
+    pruning strategy name.
+
+    The pruning function filters out operations based on certain
+    criteria such as dominated operations, non-immediate machines, etc.
+
+    Args:
+        pruning_function:
+            The name of the pruning function to be used. Supported values are
+            'dominated_operations' and 'non_immediate_machines'.
+
+    Returns:
+        A function that takes a Dispatcher instance and a list of Operation
+        instances as input and returns a list of Operation instances based on
+        the specified pruning function.
+
+    Raises:
+        ValueError: If the pruning_function argument is not recognized or is
+            not supported.
+    """
+    pruning_strategies = {
+        PruningFunction.DOMINATED_OPERATIONS: prune_dominated_operations,
+        PruningFunction.NON_IMMEDIATE_MACHINES: prune_non_immediate_machines,
+    }
+
+    if pruning_function_name not in pruning_strategies:
+        raise ValueError(
+            f"Unsupported pruning function '{pruning_function_name}'. "
+            f"Supported values are {', '.join(pruning_strategies.keys())}."
+        )
+
+    return pruning_strategies[pruning_function_name]  # type: ignore[index]

job_shop_lib/dispatching/pruning_functions.py

@@ -0,0 +1,116 @@
+"""Contains functions to prune (filter) operations.
+
+This functions are used by the `Dispatcher` class to reduce the
+amount of available operations to choose from.
+"""
+
+from collections.abc import Callable, Iterable
+
+from job_shop_lib import Operation
+from job_shop_lib.dispatching import Dispatcher
+
+
+def create_composite_pruning_function(
+    pruning_functions: Iterable[
+        Callable[[Dispatcher, list[Operation]], list[Operation]]
+    ],
+) -> Callable[[Dispatcher, list[Operation]], list[Operation]]:
+    """Creates and returns a composite pruning strategy function based on the
+    specified list of pruning strategies.
+    The composite pruning strategy function filters out operations based on
+    the specified list of pruning strategies.
+    Args:
+        pruning_strategies:
+            A list of pruning strategies to be used. Supported values are
+            'dominated_operations' and 'non_immediate_machines'.
+    Returns:
+        A function that takes a Dispatcher instance and a list of Operation
+        instances as input and returns a list of Operation instances based on
+        the specified list of pruning strategies.
+    Raises:
+        ValueError: If any of the pruning strategies in the list are not
+            recognized or are not supported.
+    """
+
+    def composite_pruning_function(
+        dispatcher: Dispatcher, operations: list[Operation]
+    ) -> list[Operation]:
+        pruned_operations = operations
+        for pruning_function in pruning_functions:
+            pruned_operations = pruning_function(dispatcher, pruned_operations)
+
+        return pruned_operations
+
+    return composite_pruning_function
+
+
+def prune_dominated_operations(
+    dispatcher: Dispatcher, operations: list[Operation]
+) -> list[Operation]:
+    """Filters out all the operations that are dominated.
+    An operation is dominated if there is another operation that ends before
+    it starts on the same machine.
+    """
+
+    min_machine_end_times = _get_min_machine_end_times(dispatcher, operations)
+
+    non_dominated_operations: list[Operation] = []
+    for operation in operations:
+        # One benchmark instance has an operation with duration 0
+        if operation.duration == 0:
+            return [operation]
+        for machine_id in operation.machines:
+            start_time = dispatcher.start_time(operation, machine_id)
+            is_dominated = start_time >= min_machine_end_times[machine_id]
+            if not is_dominated:
+                non_dominated_operations.append(operation)
+                break
+
+    return non_dominated_operations
+
+
+def prune_non_immediate_machines(
+    dispatcher: Dispatcher, operations: list[Operation]
+) -> list[Operation]:
+    """Filters out all the operations associated with machines which earliest
+    operation is not the current time."""
+
+    is_immediate_machine = _get_immediate_machines(dispatcher, operations)
+    non_dominated_operations: list[Operation] = []
+    for operation in operations:
+        if any(
+            is_immediate_machine[machine_id]
+            for machine_id in operation.machines
+        ):
+            non_dominated_operations.append(operation)
+
+    return non_dominated_operations
+
+
+def _get_min_machine_end_times(
+    dispatcher: Dispatcher, available_operations: list[Operation]
+) -> list[int | float]:
+    end_times_per_machine = [float("inf")] * dispatcher.instance.num_machines
+    for op in available_operations:
+        for machine_id in op.machines:
+            start_time = dispatcher.start_time(op, machine_id)
+            end_times_per_machine[machine_id] = min(
+                end_times_per_machine[machine_id], start_time + op.duration
+            )
+    return end_times_per_machine
+
+
+def _get_immediate_machines(
+    self: Dispatcher, available_operations: list[Operation]
+) -> list[bool]:
+    """Returns the machine ids of the machines that have at least one
+    operation with the lowest start time (i.e. the start time)."""
+    working_machines = [False] * self.instance.num_machines
+    # We can't use the current_time directly because it will cause
+    # an infinite loop.
+    current_time = self.min_start_time(available_operations)
+    for op in available_operations:
+        for machine_id in op.machines:
+            if self.start_time(op, machine_id) == current_time:
+                working_machines[machine_id] = True
+    return working_machines

job_shop_lib/exceptions.py

@@ -0,0 +1,26 @@
+"""Exceptions for the job shop scheduling library."""
+
+
+class JobShopLibError(Exception):
+    """Base class for exceptions in the job shop scheduling library.
+
+    This class is the base class for all exceptions raised by the job
+    shop scheduling library.
+
+    It is useful for catching any exception that is raised by the
+    library, without having to catch each specific exception
+    separately.
+    """
+
+
+class NoSolutionFoundError(JobShopLibError):
+    """Exception raised when no solution is found by a solver.
+
+    This exception is raised by a solver when it is unable to find a
+    feasible solution within a given time limit.
+
+    It is useful to distinguish this exception from other exceptions
+    that may be raised by a solver, such as a ValueError or a
+    TypeError, which may indicate a bug in the code or an invalid
+    input, rather than a failure to find a solution.
+    """

job_shop_lib/generators/__init__.py

@@ -0,0 +1,7 @@
+"""Package for generating job shop instances."""
+
+from job_shop_lib.generators.basic_generator import BasicGenerator
+
+__all__ = [
+    "BasicGenerator",
+]