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

job_shop_lib/benchmarking/load_benchmark.py

@@ -0,0 +1,142 @@
+"""Module for loading benchmark instances.
+
+All benchmark instances are stored in a single JSON file. This module provides
+functions to load the instances from the file and return them as
+JobShopInstance objects.
+
+The contributions to this benchmark dataset are as follows:
+
+abz5-9: This subset, comprising five instances, was introduced by Adams et
+    al. (1988).
+ft06, ft10, ft20: These three instances are attributed to the work of
+    Fisher and Thompson, as detailed in their 1963 work.
+la01-40: A collection of forty instances, this group was contributed by
+    Lawrence, as referenced in his 1984 report.
+orb01-10: Ten instances in this category were provided by Applegate and
+    Cook, as seen in their 1991 study.
+swb01-20: This segment, encompassing twenty instances, was contributed by
+    Storer et al., as per their 1992 article.
+yn1-4: Yamada and Nakano are credited with the addition of four instances
+    in this group, as found in their 1992 paper.
+ta01-80: The largest contribution, consisting of eighty instances, was
+    made by Taillard, as documented in his 1993 paper.
+
+The metadata from these instances has been updated using data from:
+
+Thomas Weise. jsspInstancesAndResults. Accessed in January 2024.
+Available at: https://github.com/thomasWeise/jsspInstancesAndResults
+
+It includes the following information:
+    - "optimum" (int | None): The optimal makespan for the instance.
+    - "lower_bound" (int): The lower bound for the makespan. If
+        optimality is known, it is equal to the optimum.
+    - "upper_bound" (int): The upper bound for the makespan. If
+        optimality is known, it is equal to the optimum.
+    - "reference" (str): The paper or source where the instance was first
+        introduced.
+
+References:
+    - J. Adams, E. Balas, and D. Zawack, "The shifting bottleneck procedure
+        for job shop scheduling," Management Science, vol. 34, no. 3,
+        pp. 391–401, 1988.
+
+    - J.F. Muth and G.L. Thompson, Industrial scheduling. Englewood Cliffs,
+        NJ: Prentice-Hall, 1963.
+
+    - S. Lawrence, "Resource constrained project scheduling: An experimental
+        investigation of heuristic scheduling techniques (Supplement),"
+        Carnegie-Mellon University, Graduate School of Industrial
+        Administration, Pittsburgh, Pennsylvania, 1984.
+
+    - D. Applegate and W. Cook, "A computational study of job-shop
+        scheduling," ORSA Journal on Computer, vol. 3, no. 2, pp. 149–156,
+        1991.
+
+    - R.H. Storer, S.D. Wu, and R. Vaccari, "New search spaces for
+        sequencing problems with applications to job-shop scheduling,"
+        Management Science, vol. 38, no. 10, pp. 1495–1509, 1992.
+
+    - T. Yamada and R. Nakano, "A genetic algorithm applicable to
+        large-scale job-shop problems," in Proceedings of the Second
+        International Workshop on Parallel Problem Solving from Nature
+        (PPSN'2), Brussels, Belgium, pp. 281–290, 1992.
+
+    - E. Taillard, "Benchmarks for basic scheduling problems," European
+        Journal of Operational Research, vol. 64, no. 2, pp. 278–285, 1993.
+"""
+
+from typing import Any
+
+import functools
+import json
+from importlib import resources
+
+from job_shop_lib import JobShopInstance
+
+
+@functools.cache
+def load_all_benchmark_instances() -> dict[str, JobShopInstance]:
+    """Loads all benchmark instances available.
+
+    Returns:
+        A dictionary containing the names of the benchmark instances as keys
+        and the corresponding JobShopInstance objects as values.
+
+    """
+    benchmark_instances_dict = load_benchmark_json()
+    return {
+        name: load_benchmark_instance(name)
+        for name in benchmark_instances_dict
+    }
+
+
+def load_benchmark_instance(name: str) -> JobShopInstance:
+    """Loads a specific benchmark instance.
+
+    Calls to `load_benchmark_json` to load the benchmark instances from the
+    JSON file. The instance is then loaded from the dictionary using the
+    provided name. Since `load_benchmark_json` is cached, the file is only
+    read once.
+
+    Args:
+        name: The name of the benchmark instance to load. Can be one of the
+            following: "abz5-9", "ft06", "ft10", "ft20", "la01-40", "orb01-10",
+            "swb01-20", "yn1-4", or "ta01-80".
+    """
+    benchmark_dict = load_benchmark_json()[name]
+    return JobShopInstance.from_matrices(
+        duration_matrix=benchmark_dict["duration_matrix"],
+        machines_matrix=benchmark_dict["machines_matrix"],
+        name=name,
+        metadata=benchmark_dict["metadata"],
+    )
+
+
+@functools.cache
+def load_benchmark_json() -> dict[str, dict[str, Any]]:
+    """Loads the raw JSON file containing the benchmark instances.
+
+    Results are cached to avoid reading the file multiple times.
+
+    Each instance is represented as a dictionary with the following keys
+    and values:
+        - "name" (str): The name of the instance.
+        - "duration_matrix" (list[list[int]]): The matrix containing the
+            durations for each operation.
+        - "machines_matrix" (list[list[int]]): The matrix containing the
+            machines for each operation.
+        - "metadata" (dict[str, Any]): A dictionary containing metadata
+            about the instance. The keys are "optimum" (int | None),
+            "lower_bound" (int), "upper_bound" (int),
+            and "reference" (str).
+
+    Returns:
+        The dictionary containing the benchmark instances.
+    """
+    benchmark_file = (
+        resources.files("job_shop_lib.benchmarking")
+        / "benchmark_instances.json"
+    )
+
+    with benchmark_file.open("r", encoding="utf-8") as f:
+        return json.load(f)

job_shop_lib/cp_sat/__init__.py

@@ -0,0 +1,5 @@
+from job_shop_lib.cp_sat.ortools_solver import ORToolsSolver
+
+__all__ = [
+    "ORToolsSolver",
+]

job_shop_lib/cp_sat/ortools_solver.py

@@ -0,0 +1,201 @@
+"""Home of the ORToolsSolver class."""
+
+from __future__ import annotations
+
+import time
+
+from ortools.sat.python import cp_model
+from ortools.sat.python.cp_model import IntVar
+
+from job_shop_lib import (
+    JobShopInstance,
+    Schedule,
+    ScheduledOperation,
+    Operation,
+)
+from job_shop_lib import NoSolutionFoundError, BaseSolver
+
+
+class ORToolsSolver(BaseSolver):
+    """A solver for the job shop scheduling problem using constraint
+    programming.
+
+    This solver uses the ortools library to solve the job shop scheduling
+    problem using constraint programming.
+    """
+
+    def __init__(
+        self,
+        max_time_in_seconds: float | None = None,
+        log_search_progress: bool = False,
+    ):
+        self.log_search_progress = log_search_progress
+        self.max_time_in_seconds = max_time_in_seconds
+
+        self.makespan: cp_model.IntVar | None = None
+        self.model = cp_model.CpModel()
+        self.solver = cp_model.CpSolver()
+        self._operations_start: dict[Operation, tuple[IntVar, IntVar]] = {}
+
+    def __call__(self, instance: JobShopInstance) -> Schedule:
+        # Re-defined here since we already add metadata to the schedule in
+        # the solve method.
+        return self.solve(instance)
+
+    def solve(self, instance: JobShopInstance) -> Schedule:
+        """Creates the variables, constraints and objective, and solves the
+        problem.
+
+        If a solution is found, it extracts and returns the start times of
+        each operation and the makespan. If no solution is found, it raises
+        a NoSolutionFound exception.
+        """
+        self._initialize_model(instance)
+
+        start_time = time.perf_counter()
+        status = self.solver.Solve(self.model)
+        elapsed_time = time.perf_counter() - start_time
+
+        if status not in {cp_model.OPTIMAL, cp_model.FEASIBLE}:
+            raise NoSolutionFoundError(
+                f"No solution could be found for the given problem. "
+                f"Elapsed time: {elapsed_time} seconds."
+            )
+        if self.makespan is None:
+            # Check added to satisfy mypy
+            raise ValueError("The makespan variable was not set.")
+
+        metadata = {
+            "status": "optimal" if status == cp_model.OPTIMAL else "feasible",
+            "elapsed_time": elapsed_time,
+            "makespan": self.solver.Value(self.makespan),
+            "solved_by": "ORToolsSolver",
+        }
+        return self._create_schedule(instance, metadata)
+
+    def _initialize_model(self, instance: JobShopInstance):
+        """Initializes the model with variables, constraints and objective.
+
+        The model is initialized with two variables for each operation: start
+        and end time. The constraints ensure that operations within a job are
+        performed in sequence and that operations assigned to the same machine
+        do not overlap. The objective is to minimize the makespan.
+
+        Args:
+            instance: The job shop instance to be solved.
+        """
+        self.model = cp_model.CpModel()
+        self.solver = cp_model.CpSolver()
+        self.solver.parameters.log_search_progress = self.log_search_progress
+        self._operations_start = {}
+        if self.max_time_in_seconds is not None:
+            self.solver.parameters.max_time_in_seconds = (
+                self.max_time_in_seconds
+            )
+        self._create_variables(instance)
+        self._add_constraints(instance)
+        self._set_objective(instance)
+
+    def _create_schedule(
+        self, instance: JobShopInstance, metadata: dict[str, object]
+    ) -> Schedule:
+        """Creates a Schedule object from the solution."""
+        operations_start: dict[Operation, int] = {
+            operation: self.solver.Value(start_var)
+            for operation, (start_var, _) in self._operations_start.items()
+        }
+
+        unsorted_schedule: list[list[ScheduledOperation]] = [
+            [] for _ in range(instance.num_machines)
+        ]
+        for operation, start_time in operations_start.items():
+            unsorted_schedule[operation.machine_id].append(
+                ScheduledOperation(operation, start_time, operation.machine_id)
+            )
+
+        sorted_schedule = [
+            sorted(scheduled_operation, key=lambda x: x.start_time)
+            for scheduled_operation in unsorted_schedule
+        ]
+
+        return Schedule(
+            instance=instance, schedule=sorted_schedule, **metadata
+        )
+
+    def _create_variables(self, instance: JobShopInstance):
+        """Creates two variables for each operation: start and end time."""
+        for job in instance.jobs:
+            for operation in job:
+                start_var = self.model.NewIntVar(
+                    0, instance.total_duration, f"start_{operation}"
+                )
+                end_var = self.model.NewIntVar(
+                    0, instance.total_duration, f"end_{operation}"
+                )
+                self._operations_start[operation] = (start_var, end_var)
+                self.model.Add(end_var == start_var + operation.duration)
+
+    def _add_constraints(self, instance: JobShopInstance):
+        """Adds job and machine constraints.
+
+        Job Constraints: Ensure that operations within a job are performed in
+        sequence. If operation A must precede operation B in a job, we ensure
+        A's end time is less than or equal to B's start time.
+
+        Machine Constraints: Operations assigned to the same machine cannot
+        overlap. This is ensured by creating interval variables (which
+        represent the duration an operation occupies a machine)
+        and adding a 'no overlap' constraint for these intervals on
+        each machine.
+        """
+        self._add_job_constraints(instance)
+        self._add_machine_constraints(instance)
+
+    def _set_objective(self, instance: JobShopInstance):
+        """The objective is to minimize the makespan, which is the total
+        duration of the schedule."""
+        self.makespan = self.model.NewIntVar(
+            0, instance.total_duration, "makespan"
+        )
+        end_times = [end for _, end in self._operations_start.values()]
+        self.model.AddMaxEquality(self.makespan, end_times)
+        self.model.Minimize(self.makespan)
+
+    def _add_job_constraints(self, instance: JobShopInstance):
+        """Adds job constraints to the model. Operations within a job must be
+        performed in sequence. If operation A must precede operation B in a
+        job, we ensure A's end time is less than or equal to B's start time."""
+        for job in instance.jobs:
+            for position in range(1, len(job)):
+                self.model.Add(
+                    self._operations_start[job[position - 1]][1]
+                    <= self._operations_start[job[position]][0]
+                )
+
+    def _add_machine_constraints(self, instance: JobShopInstance):
+        """Adds machine constraints to the model. Operations assigned to the
+        same machine cannot overlap. This is ensured by creating interval
+        variables (which represent the duration an operation occupies a
+        machine) and adding a 'no overlap' constraint for these intervals on
+        each machine."""
+
+        # Create interval variables for each operation on each machine
+        machines_operations: list[list[tuple[tuple[IntVar, IntVar], int]]] = [
+            [] for _ in range(instance.num_machines)
+        ]
+        for job in instance.jobs:
+            for operation in job:
+                machines_operations[operation.machine_id].append(
+                    (
+                        self._operations_start[operation],
+                        operation.duration,
+                    )
+                )
+        for machine_id, operations in enumerate(machines_operations):
+            intervals = []
+            for (start_var, end_var), duration in operations:
+                interval_var = self.model.NewIntervalVar(
+                    start_var, duration, end_var, f"interval_{machine_id}"
+                )
+                intervals.append(interval_var)
+            self.model.AddNoOverlap(intervals)

job_shop_lib/dispatching/__init__.py

@@ -0,0 +1,49 @@
+"""Package containing all the functionality to solve the Job Shop Scheduling
+Problem step-by-step."""
+
+from job_shop_lib.dispatching.dispatcher import Dispatcher
+from job_shop_lib.dispatching.dispatching_rules import (
+    shortest_processing_time_rule,
+    first_come_first_served_rule,
+    most_work_remaining_rule,
+    most_operations_remaining_rule,
+    random_operation_rule,
+)
+from job_shop_lib.dispatching.pruning_functions import (
+    prune_dominated_operations,
+    prune_non_immediate_machines,
+    create_composite_pruning_function,
+)
+from job_shop_lib.dispatching.factories import (
+    PruningFunction,
+    DispatchingRule,
+    MachineChooser,
+    dispatching_rule_factory,
+    machine_chooser_factory,
+    pruning_function_factory,
+    composite_pruning_function_factory,
+)
+from job_shop_lib.dispatching.dispatching_rule_solver import (
+    DispatchingRuleSolver,
+)
+
+
+__all__ = [
+    "dispatching_rule_factory",
+    "machine_chooser_factory",
+    "shortest_processing_time_rule",
+    "first_come_first_served_rule",
+    "most_work_remaining_rule",
+    "most_operations_remaining_rule",
+    "random_operation_rule",
+    "DispatchingRule",
+    "MachineChooser",
+    "Dispatcher",
+    "DispatchingRuleSolver",
+    "prune_dominated_operations",
+    "prune_non_immediate_machines",
+    "create_composite_pruning_function",
+    "PruningFunction",
+    "pruning_function_factory",
+    "composite_pruning_function_factory",
+]

job_shop_lib/dispatching/dispatcher.py

@@ -0,0 +1,269 @@
+"""Home of the `Dispatcher` class."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from collections import deque
+
+from job_shop_lib import (
+    JobShopInstance,
+    Schedule,
+    ScheduledOperation,
+    Operation,
+)
+
+
+class Dispatcher:
+    """Handles the logic of scheduling operations on machines.
+
+    This class allow us to just define the order in which operations are
+    sequenced and the machines in which they are processed. It is then
+    responsible for scheduling the operations on the machines and keeping
+    track of the next available time for each machine and job.
+
+    Attributes:
+        instance:
+            The instance of the job shop problem to be scheduled.
+        schedule:
+            The schedule of operations on machines.
+        pruning_function:
+            The pipeline of pruning methods to be used to filter out
+            operations from the list of available operations.
+    """
+
+    __slots__ = (
+        "instance",
+        "schedule",
+        "_machine_next_available_time",
+        "_job_next_operation_index",
+        "_job_next_available_time",
+        "pruning_function",
+    )
+
+    def __init__(
+        self,
+        instance: JobShopInstance,
+        pruning_function: (
+            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.
+            pruning_strategies:
+                A list of pruning strategies to be used to filter out
+                operations from the list of available operations. Supported
+                values are 'dominated_operations' and 'non_immediate_machines'.
+                Defaults to [PruningStrategy.DOMINATED_OPERATIONS]. To disable
+                pruning, pass an empty list.
+        """
+
+        self.instance = instance
+        self.schedule = Schedule(self.instance)
+        self._machine_next_available_time = [0] * self.instance.num_machines
+        self._job_next_operation_index = [0] * self.instance.num_jobs
+        self._job_next_available_time = [0] * self.instance.num_jobs
+        self.pruning_function = pruning_function
+
+    @property
+    def machine_next_available_time(self) -> list[int]:
+        """Returns the next available time for each machine."""
+        return self._machine_next_available_time
+
+    @property
+    def job_next_operation_index(self) -> list[int]:
+        """Returns the index of the next operation to be scheduled for each
+        job."""
+        return self._job_next_operation_index
+
+    @property
+    def job_next_available_time(self) -> list[int]:
+        """Returns the next available time for each job."""
+        return self._job_next_available_time
+
+    @classmethod
+    def create_schedule_from_raw_solution(
+        cls, instance: JobShopInstance, raw_solution: list[list[Operation]]
+    ) -> Schedule:
+        """Creates a schedule from a raw solution.
+
+        A raw solution is a list of lists of operations, where each list
+        represents the order of operations for a machine.
+
+        Args:
+            instance:
+                The instance of the job shop problem to be solved.
+            raw_solution:
+                A list of lists of operations, where each list represents the
+                order of operations for a machine.
+
+        Returns:
+            A Schedule object representing the solution.
+        """
+        dispatcher = cls(instance)
+        dispatcher.reset()
+        raw_solution_deques = [
+            deque(operations) for operations in raw_solution
+        ]
+        while not dispatcher.schedule.is_complete():
+            for machine_id, operations in enumerate(raw_solution_deques):
+                if not operations:
+                    continue
+                operation = operations[0]
+                if dispatcher.is_operation_ready(operation):
+                    dispatcher.dispatch(operation, machine_id)
+                    operations.popleft()
+        return dispatcher.schedule
+
+    def reset(self) -> None:
+        """Resets the dispatcher to its initial state."""
+        self.schedule.reset()
+        self._machine_next_available_time = [0] * self.instance.num_machines
+        self._job_next_operation_index = [0] * self.instance.num_jobs
+        self._job_next_available_time = [0] * self.instance.num_jobs
+
+    def dispatch(self, operation: Operation, machine_id: int) -> None:
+        """Schedules the given operation on the given machine.
+
+        The start time of the operation is computed based on the next
+        available time for the machine and the next available time for the
+        job to which the operation belongs. The operation is then scheduled
+        on the machine and the tracking attributes are updated.
+        Args:
+            operation:
+                The operation to be scheduled.
+            machine_id:
+                The id of the machine on which the operation is to be
+                scheduled.
+
+        Raises:
+            ValueError: If the operation is not ready to be scheduled.
+        """
+
+        if not self.is_operation_ready(operation):
+            raise ValueError("Operation is not ready to be scheduled.")
+
+        start_time = self.start_time(operation, machine_id)
+
+        scheduled_operation = ScheduledOperation(
+            operation, start_time, machine_id
+        )
+        self.schedule.add(scheduled_operation)
+        self._update_tracking_attributes(scheduled_operation)
+
+    def is_operation_ready(self, operation: Operation) -> bool:
+        """Returns True if the given operation is ready to be scheduled.
+
+        An operation is ready to be scheduled if it is the next operation
+        to be scheduled for its job.
+
+        Args:
+            operation:
+                The operation to be checked.
+        """
+        return (
+            self.job_next_operation_index[operation.job_id]
+            == operation.position_in_job
+        )
+
+    def start_time(self, operation: Operation, machine_id: int) -> int:
+        """Computes the start time for the given operation on the given
+        machine.
+
+        The start time is the maximum of the next available time for the
+        machine and the next available time for the job to which the
+        operation belongs.
+
+        Args:
+            operation:
+                The operation to be scheduled.
+            machine_id:
+                The id of the machine on which the operation is to be
+                scheduled.
+        """
+        return max(
+            self.machine_next_available_time[machine_id],
+            self.job_next_available_time[operation.job_id],
+        )
+
+    def _update_tracking_attributes(
+        self, scheduled_operation: ScheduledOperation
+    ) -> None:
+        # Variables defined here to make the lines shorter
+        job_id = scheduled_operation.job_id
+        machine_id = scheduled_operation.machine_id
+        end_time = scheduled_operation.end_time
+
+        self.machine_next_available_time[machine_id] = end_time
+        self.job_next_operation_index[job_id] += 1
+        self.job_next_available_time[job_id] = end_time
+
+    def current_time(self) -> int:
+        """Returns the current time of the schedule.
+
+        The current time is the minimum start time of the available
+        operations.
+        """
+        available_operations = self.available_operations()
+        return self.min_start_time(available_operations)
+
+    def min_start_time(self, operations: list[Operation]) -> int:
+        """Returns the minimum start time of the available operations."""
+        if not operations:
+            return self.schedule.makespan()
+        min_start_time = float("inf")
+        for op in operations:
+            for machine_id in op.machines:
+                start_time = self.start_time(op, machine_id)
+                min_start_time = min(min_start_time, start_time)
+        return int(min_start_time)
+
+    def uncompleted_operations(self) -> list[Operation]:
+        """Returns the list of operations that have not been scheduled.
+
+        An operation is uncompleted if it has not been scheduled yet.
+
+        It is more efficient than checking all operations in the instance.
+        """
+        uncompleted_operations = []
+        for job_id, next_position in enumerate(self.job_next_operation_index):
+            operations = self.instance.jobs[job_id][next_position:]
+            uncompleted_operations.extend(operations)
+        return uncompleted_operations
+
+    def available_operations(self) -> list[Operation]:
+        """Returns a list of available operations for processing, optionally
+        filtering out operations known to be bad choices.
+
+        This method first gathers all possible next operations from the jobs
+        being processed. It then optionally filters these operations to exclude
+        ones that are deemed inefficient or suboptimal choices.
+
+        An operation is sub-optimal if there is another operation that could
+        be scheduled in the same machine that would finish before the start
+        time of the sub-optimal operation.
+
+        Returns:
+            A list of Operation objects that are available for scheduling.
+
+        Raises:
+            ValueError: If using the filter_bad_choices option and one of the
+                available operations can be scheduled in more than one machine.
+        """
+        available_operations = self._available_operations()
+        if self.pruning_function is not None:
+            available_operations = self.pruning_function(
+                self, available_operations
+            )
+        return available_operations
+
+    def _available_operations(self) -> list[Operation]:
+        available_operations = []
+        for job_id, next_position in enumerate(self.job_next_operation_index):
+            if next_position == len(self.instance.jobs[job_id]):
+                continue
+            operation = self.instance.jobs[job_id][next_position]
+            available_operations.append(operation)
+        return available_operations