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

job_shop_lib/benchmarking/_load_benchmark.py

@@ -0,0 +1,88 @@
+"""Contains functions to load benchmark instances from a JSON file."""
+
+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 :class:`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 :func:`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``)
+      * ``reference`` (``str``)
+
+    Note:
+        This dictionary is the standard way to represent instances in
+        JobShopLib. You can obtain the dictionary of each instance with
+        :class:`~job_shop_lib.JobShopInstance`'s
+        :meth:`~job_shop_lib.JobShopInstance.to_dict` method.
+
+    Returns:
+        The dictionary containing the benchmark instances represented as
+        dictionaries.
+    """
+    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/constraint_programming/__init__.py

@@ -0,0 +1,13 @@
+"""Contains solvers based on Constraint Programming (CP).
+
+CP defines the Job Shop Scheduling Problem through constraints
+and focuses on finding a feasible solution. It usually aims to minimize an
+objective function, typically the makespan. One of the advantages of these
+methods is that they are not restricted to linear constraints.
+"""
+
+from job_shop_lib.constraint_programming._ortools_solver import ORToolsSolver
+
+__all__ = [
+    "ORToolsSolver",
+]

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

@@ -1,4 +1,4 @@
-"""Home of the ORToolsSolver class."""
+"""Home of the `ORToolsSolver` class."""
 
 from __future__ import annotations
 
@@ -13,15 +13,31 @@ 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.
-
-    This solver uses the ortools library to solve the job shop scheduling
-    problem using constraint programming.
+    """Solver based on `OR-Tools' CP-SAT
+    <https://developers.google.com/optimization/cp/cp_solver>`_ solver.
+
+    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>`_.
     """
 
     def __init__(
@@ -29,10 +45,22 @@ 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
 
-        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]] = {}
@@ -46,9 +74,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 +102,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)
@@ -154,12 +193,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

job_shop_lib/dispatching/__init__.py

@@ -1,52 +1,56 @@
-"""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,
+.. autosummary::
+    :nosignatures:
+
+    Dispatcher
+    DispatcherObserver
+    HistoryObserver
+    UnscheduledOperationsObserver
+    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.pruning_functions import (
-    prune_dominated_operations,
-    prune_non_immediate_machines,
-    create_composite_pruning_function,
+from ._unscheduled_operations_observer import (
+    UnscheduledOperationsObserver,
 )
-from job_shop_lib.dispatching.factories import (
-    PruningFunction,
-    DispatchingRule,
-    MachineChooser,
-    dispatching_rule_factory,
-    machine_chooser_factory,
-    pruning_function_factory,
-    composite_pruning_function_factory,
+from ._ready_operation_filters import (
+    filter_dominated_operations,
+    filter_non_immediate_machines,
+    ReadyOperationsFilter,
 )
-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",
 ]