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

job_shop_lib/{cp_sat/ortools_solver.py → constraint_programming/_ortools_solver.py}

@@ -1,7 +1,8 @@
-"""Home of the ORToolsSolver class."""
+"""Home of the `ORToolsSolver` class."""
 
 from __future__ import annotations
 
+from typing import Any, Dict, List, Tuple
 import time
 
 from ortools.sat.python import cp_model
@@ -13,15 +14,41 @@ from job_shop_lib import (
     ScheduledOperation,
     Operation,
 )
-from job_shop_lib import NoSolutionFoundError, BaseSolver
+from job_shop_lib import BaseSolver
+from job_shop_lib.exceptions import NoSolutionFoundError
 
 
 class ORToolsSolver(BaseSolver):
-    """A solver for the job shop scheduling problem using constraint
-    programming.
+    """Solver based on `OR-Tools' CP-SAT
+    <https://developers.google.com/optimization/cp/cp_solver>`_ solver.
 
-    This solver uses the ortools library to solve the job shop scheduling
-    problem using constraint programming.
+    Attributes:
+        log_search_progress (bool):
+            Whether to log the search progress to the console.
+        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):
+            The `OR-Tools' CP-SAT model
+            <https://developers.google.com/optimization/reference/python/sat/
+            python/cp_model#cp_model.CpModel>`_.
+        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__(
@@ -32,12 +59,29 @@ class ORToolsSolver(BaseSolver):
         self.log_search_progress = log_search_progress
         self.max_time_in_seconds = max_time_in_seconds
 
-        self.makespan: cp_model.IntVar | None = None
+        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]] = {}
+        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)
@@ -46,9 +90,22 @@ class ORToolsSolver(BaseSolver):
         """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.
+        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"``
+
+        Raises:
+            NoSolutionFoundError:
+                If no solution could be found for the given problem within the
+                time limit.
         """
         self._initialize_model(instance)
 
@@ -61,14 +118,12 @@ class ORToolsSolver(BaseSolver):
                 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.")
+        assert self._makespan is not None  # Make mypy happy
 
         metadata = {
             "status": "optimal" if status == cp_model.OPTIMAL else "feasible",
             "elapsed_time": elapsed_time,
-            "makespan": self.solver.Value(self.makespan),
+            "makespan": self.solver.Value(self._makespan),
             "solved_by": "ORToolsSolver",
         }
         return self._create_schedule(instance, metadata)
@@ -97,15 +152,15 @@ class ORToolsSolver(BaseSolver):
         self._set_objective(instance)
 
     def _create_schedule(
-        self, instance: JobShopInstance, metadata: dict[str, object]
+        self, instance: JobShopInstance, metadata: Dict[str, Any]
     ) -> Schedule:
         """Creates a Schedule object from the solution."""
-        operations_start: dict[Operation, int] = {
+        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]] = [
+        unsorted_schedule: List[List[ScheduledOperation]] = [
             [] for _ in range(instance.num_machines)
         ]
         for operation, start_time in operations_start.items():
@@ -154,12 +209,12 @@ class ORToolsSolver(BaseSolver):
     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(
+        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)
+        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
@@ -180,7 +235,7 @@ class ORToolsSolver(BaseSolver):
         each machine."""
 
         # Create interval variables for each operation on each machine
-        machines_operations: list[list[tuple[tuple[IntVar, IntVar], int]]] = [
+        machines_operations: List[List[Tuple[Tuple[IntVar, IntVar], int]]] = [
             [] for _ in range(instance.num_machines)
         ]
         for job in instance.jobs:

job_shop_lib/dispatching/__init__.py

@@ -1,52 +1,61 @@
-"""Package containing all the functionality to solve the Job Shop Scheduling
-Problem step-by-step."""
+"""Contains classes and functions to solve the Job Shop Scheduling
+Problem step-by-step.
 
-from job_shop_lib.dispatching.dispatcher import Dispatcher, DispatcherObserver
-from job_shop_lib.dispatching.history_tracker import HistoryTracker
-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,
+.. autosummary::
+    :nosignatures:
+
+    Dispatcher
+    DispatcherObserver
+    HistoryObserver
+    UnscheduledOperationsObserver
+    OptimalOperationsObserver
+    ReadyOperationsFilter
+    DispatcherObserverConfig
+    filter_dominated_operations
+    filter_non_immediate_machines
+    create_composite_operation_filter
+    ReadyOperationsFilterType
+    ready_operations_filter_factory
+
+Dispatching refers to the decision-making process of selecting which job
+should be processed next on a particular machine when that machine becomes
+available.
+"""
+
+from ._dispatcher import Dispatcher, DispatcherObserver
+from ._history_observer import (
+    HistoryObserver,
 )
-from job_shop_lib.dispatching.factories import (
-    PruningFunction,
-    DispatchingRule,
-    MachineChooser,
-    dispatching_rule_factory,
-    machine_chooser_factory,
-    pruning_function_factory,
-    composite_pruning_function_factory,
+from ._unscheduled_operations_observer import UnscheduledOperationsObserver
+from ._optimal_operations_observer import OptimalOperationsObserver
+from ._ready_operation_filters import (
+    filter_dominated_operations,
+    filter_non_immediate_machines,
+    ReadyOperationsFilter,
+    filter_non_idle_machines,
+    filter_non_immediate_operations,
 )
-from job_shop_lib.dispatching.dispatching_rule_solver import (
-    DispatchingRuleSolver,
+from ._dispatcher_observer_config import DispatcherObserverConfig
+from ._factories import (
+    ReadyOperationsFilterType,
+    ready_operations_filter_factory,
+    create_composite_operation_filter,
 )
 
 
 __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",
+    "filter_dominated_operations",
+    "filter_non_immediate_machines",
+    "create_composite_operation_filter",
+    "ReadyOperationsFilterType",
+    "ready_operations_filter_factory",
     "DispatcherObserver",
-    "HistoryTracker",
+    "HistoryObserver",
+    "DispatcherObserverConfig",
+    "UnscheduledOperationsObserver",
+    "ReadyOperationsFilter",
+    "filter_non_idle_machines",
+    "filter_non_immediate_operations",
+    "OptimalOperationsObserver",
 ]