job-shop-lib 1.0.0a5__py3-none-any.whl → 1.0.0b2__py3-none-any.whl

job_shop_lib/dispatching/rules/_dispatching_rules_functions.py

@@ -6,6 +6,7 @@ which operations are selected for execution based on certain criteria such as
 shortest processing time, first come first served, etc.
 """
 
+from typing import List, Optional
 from collections.abc import Callable, Sequence
 import random
 
@@ -88,7 +89,7 @@ def score_based_rule(
 
 
 def score_based_rule_with_tie_breaker(
-    score_functions: list[Callable[[Dispatcher], Sequence[int]]],
+    score_functions: List[Callable[[Dispatcher], Sequence[int]]],
 ) -> Callable[[Dispatcher], Operation]:
     """Creates a dispatching rule based on multiple scoring functions.
 
@@ -122,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
@@ -131,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
@@ -153,9 +154,9 @@ class MostWorkRemainingScorer:  # pylint: disable=too-few-public-methods
     """
 
     def __init__(self) -> None:
-        self._duration_observer: DurationObserver | None = None
-        self._is_ready_observer: IsReadyObserver | None = None
-        self._current_dispatcher: Dispatcher | None = 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."""
@@ -197,7 +198,7 @@ observer_based_most_work_remaining_rule = score_based_rule(
 )
 
 
-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
@@ -206,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

@@ -5,6 +5,7 @@ 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
@@ -25,7 +26,7 @@ MachineChooser = Callable[[Dispatcher, Operation], int]
 
 
 def machine_chooser_factory(
-    machine_chooser: str | MachineChooser,
+    machine_chooser: Union[str, MachineChooser],
 ) -> MachineChooser:
     """Creates and returns a machine chooser function based on the specified
     machine chooser strategy name.
@@ -36,7 +37,7 @@ def machine_chooser_factory(
     machine randomly.
 
     Args:
-        machine_chooser (str): The name of the machine chooser strategy to be
+        machine_chooser: The name of the machine chooser strategy to be
             used. Supported values are 'first' and 'random'.
 
     Returns:
@@ -49,7 +50,7 @@ def machine_chooser_factory(
         ValueError: If the machine_chooser argument is not recognized or is
             not supported.
     """
-    machine_choosers: dict[str, Callable[[Dispatcher, Operation], int]] = {
+    machine_choosers: Dict[str, Callable[[Dispatcher, Operation], int]] = {
         MachineChooserType.FIRST: lambda _, operation: operation.machines[0],
         MachineChooserType.RANDOM: lambda _, operation: random.choice(
             operation.machines

job_shop_lib/dispatching/rules/_utils.py

@@ -1,5 +1,6 @@
 """Utility functions."""
 
+from typing import Union, List
 import time
 from collections.abc import Callable
 import pandas as pd
@@ -10,12 +11,12 @@ from job_shop_lib.dispatching import Dispatcher
 
 
 def benchmark_dispatching_rules(
-    dispatching_rules: (
-        list[str | Callable[[Dispatcher], Operation]]
-        | list[str]
-        | list[Callable[[Dispatcher], Operation]]
-    ),
-    instances: list[JobShopInstance],
+    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.
 
@@ -30,7 +31,7 @@ def benchmark_dispatching_rules(
             either a string (name of a built-in rule) or a callable
             (custom rule function).
         instances:
-             iList of :class:`JobShopInstance` objects to be solved.
+            List of :class:`JobShopInstance` objects to be solved.
 
     Returns:
         A pandas DataFrame with columns:
@@ -111,7 +112,7 @@ if __name__ == "__main__":
     instances_ = [load_benchmark_instance(f"ta{i:02d}") for i in range(1, 3)]
 
     # Define rules
-    rules_: list[str | Callable[[Dispatcher], Operation]] = [
+    rules_: List[str | Callable[[Dispatcher], Operation]] = [
         "most_work_remaining",
         "shortest_processing_time",
         most_work_remaining_rule,

job_shop_lib/generation/__init__.py

@@ -1,5 +1,10 @@
 """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,
@@ -8,4 +13,7 @@ from job_shop_lib.generation._general_instance_generator import (
 __all__ = [
     "InstanceGenerator",
     "GeneralInstanceGenerator",
+    "generate_duration_matrix",
+    "generate_machine_matrix_with_recirculation",
+    "generate_machine_matrix_without_recirculation",
 ]

job_shop_lib/generation/_general_instance_generator.py

@@ -1,10 +1,16 @@
 """Home of the `BasicGenerator` class."""
 
+from typing import Optional, Tuple, Union
 import random
 
-from job_shop_lib import JobShopInstance, Operation
+from job_shop_lib import JobShopInstance
 from job_shop_lib.exceptions import ValidationError
-from job_shop_lib.generation import InstanceGenerator
+from job_shop_lib.generation import (
+    InstanceGenerator,
+    generate_duration_matrix,
+    generate_machine_matrix_with_recirculation,
+    generate_machine_matrix_without_recirculation,
+)
 
 
 class GeneralInstanceGenerator(InstanceGenerator):
@@ -20,6 +26,8 @@ class GeneralInstanceGenerator(InstanceGenerator):
     multiple instances, controlled by the ``iteration_limit`` parameter. It
     implements the iterator protocol, allowing it to be used in a ``for`` loop.
 
+    The number of operations per machine is equal to the number of machines
+
     Note:
         When used as an iterator, the generator will produce instances until it
         reaches the specified ``iteration_limit``. If ``iteration_limit`` is
@@ -73,15 +81,15 @@ class GeneralInstanceGenerator(InstanceGenerator):
 
     def __init__(  # pylint: disable=too-many-arguments
         self,
-        num_jobs: int | tuple[int, int] = (10, 20),
-        num_machines: int | tuple[int, int] = (5, 10),
-        duration_range: tuple[int, int] = (1, 99),
+        num_jobs: Union[int, Tuple[int, int]] = (10, 20),
+        num_machines: Union[int, Tuple[int, int]] = (5, 10),
+        duration_range: Tuple[int, int] = (1, 99),
         allow_less_jobs_than_machines: bool = True,
         allow_recirculation: bool = False,
-        machines_per_operation: int | tuple[int, int] = 1,
+        machines_per_operation: Union[int, Tuple[int, int]] = 1,
         name_suffix: str = "classic_generated_instance",
-        seed: int | None = None,
-        iteration_limit: int | None = None,
+        seed: Optional[int] = None,
+        iteration_limit: Optional[int] = None,
     ):
         super().__init__(
             num_jobs=num_jobs,
@@ -96,6 +104,10 @@ class GeneralInstanceGenerator(InstanceGenerator):
                 machines_per_operation,
                 machines_per_operation,
             )
+        if machines_per_operation != (1, 1):
+            raise NotImplementedError(
+                "The number of machines per operation must be 1 for now."
+            )
         self.machines_per_operation = machines_per_operation
 
         self.allow_less_jobs_than_machines = allow_less_jobs_than_machines
@@ -114,7 +126,9 @@ class GeneralInstanceGenerator(InstanceGenerator):
         )
 
     def generate(
-        self, num_jobs: int | None = None, num_machines: int | None = None
+        self,
+        num_jobs: Optional[int] = None,
+        num_machines: Optional[int] = None,
     ) -> JobShopInstance:
         if num_jobs is None:
             num_jobs = random.randint(*self.num_jobs_range)
@@ -128,60 +142,24 @@ class GeneralInstanceGenerator(InstanceGenerator):
             not self.allow_less_jobs_than_machines and num_jobs < num_machines
         ):
             raise ValidationError(
-                "Theere are fewer jobs than machines, which is not allowed"
-                "when `allow_less_jobs_than_machines` attribute is False."
+                "There are fewer jobs than machines, which is not allowed "
+                " when `allow_less_jobs_than_machines` attribute is False."
+            )
+
+        duration_matrix = generate_duration_matrix(
+            num_jobs, num_machines, self.duration_range
+        )
+        if self.allow_recirculation:
+            machine_matrix = generate_machine_matrix_with_recirculation(
+                num_jobs, num_machines
+            )
+        else:
+            machine_matrix = generate_machine_matrix_without_recirculation(
+                num_jobs, num_machines
             )
 
-        jobs = []
-        available_machines = list(range(num_machines))
-        for _ in range(num_jobs):
-            job = []
-            for _ in range(num_machines):
-                operation = self.create_random_operation(available_machines)
-                job.append(operation)
-            jobs.append(job)
-            available_machines = list(range(num_machines))
-
-        return JobShopInstance(jobs=jobs, name=self._next_name())
-
-    def create_random_operation(
-        self, available_machines: list[int] | None = None
-    ) -> Operation:
-        """Creates a random operation with the given available machines.
-
-        Args:
-            available_machines:
-                A list of available machine_ids to choose from.
-                If ``None``, all machines are available.
-        """
-        duration = random.randint(*self.duration_range)
-
-        if self.machines_per_operation[1] > 1:
-            machines = self._choose_multiple_machines()
-            return Operation(machines=machines, duration=duration)
-
-        machine_id = self._choose_one_machine(available_machines)
-        return Operation(machines=machine_id, duration=duration)
-
-    def _choose_multiple_machines(self) -> list[int]:
-        num_machines = random.randint(*self.machines_per_operation)
-        available_machines = list(range(num_machines))
-        machines = []
-        for _ in range(num_machines):
-            machine = random.choice(available_machines)
-            machines.append(machine)
-            available_machines.remove(machine)
-        return machines
-
-    def _choose_one_machine(
-        self, available_machines: list[int] | None = None
-    ) -> int:
-        if available_machines is None:
-            _, max_num_machines = self.num_machines_range
-            available_machines = list(range(max_num_machines))
-
-        machine_id = random.choice(available_machines)
-        if not self.allow_recirculation:
-            available_machines.remove(machine_id)
-
-        return machine_id
+        return JobShopInstance.from_matrices(
+            duration_matrix.tolist(),
+            machine_matrix.tolist(),
+            name=self._next_name(),
+        )

job_shop_lib/generation/_instance_generator.py

@@ -1,7 +1,9 @@
+"""Home of the `InstanceGenerator` class."""
+
 import abc
 
 import random
-from typing import Iterator
+from typing import Iterator, Optional, Tuple, Union
 
 from job_shop_lib import JobShopInstance
 from job_shop_lib.exceptions import UninitializedAttributeError
@@ -50,12 +52,12 @@ class InstanceGenerator(abc.ABC):
 
     def __init__(  # pylint: disable=too-many-arguments
         self,
-        num_jobs: int | tuple[int, int] = (10, 20),
-        num_machines: int | tuple[int, int] = (5, 10),
-        duration_range: tuple[int, int] = (1, 99),
+        num_jobs: Union[int, Tuple[int, int]] = (10, 20),
+        num_machines: Union[int, Tuple[int, int]] = (5, 10),
+        duration_range: Tuple[int, int] = (1, 99),
         name_suffix: str = "generated_instance",
-        seed: int | None = None,
-        iteration_limit: int | None = None,
+        seed: Optional[int] = None,
+        iteration_limit: Optional[int] = None,
     ):
         if isinstance(num_jobs, int):
             num_jobs = (num_jobs, num_jobs)
@@ -75,7 +77,9 @@ class InstanceGenerator(abc.ABC):
 
     @abc.abstractmethod
     def generate(
-        self, num_jobs: int | None = None, num_machines: int | None = None
+        self,
+        num_jobs: Optional[int] = None,
+        num_machines: Optional[int] = None,
     ) -> JobShopInstance:
         """Generates a single job shop instance
 

job_shop_lib/generation/_transformations.py

@@ -3,6 +3,7 @@
 import abc
 import copy
 import random
+from typing import Optional
 
 from job_shop_lib import JobShopInstance, Operation
 
@@ -38,7 +39,7 @@ class RemoveMachines(Transformation):
     """Removes operations associated with randomly selected machines until
     there are exactly num_machines machines left."""
 
-    def __init__(self, num_machines: int, suffix: str | None = None):
+    def __init__(self, num_machines: int, suffix: Optional[str] = None):
         if suffix is None:
             suffix = f"_machines={num_machines}"
         super().__init__(suffix=suffix)
@@ -83,7 +84,7 @@ class AddDurationNoise(Transformation):
         min_duration: int = 1,
         max_duration: int = 100,
         noise_level: int = 10,
-        suffix: str | None = None,
+        suffix: Optional[str] = None,
     ):
         if suffix is None:
             suffix = f"_noise={noise_level}"
@@ -127,8 +128,8 @@ class RemoveJobs(Transformation):
         self,
         min_jobs: int,
         max_jobs: int,
-        target_jobs: int | None = None,
-        suffix: str | None = None,
+        target_jobs: Optional[int] = None,
+        suffix: Optional[str] = None,
     ):
         if suffix is None:
             suffix = f"_jobs={min_jobs}-{max_jobs}"

job_shop_lib/generation/_utils.py

@@ -0,0 +1,124 @@
+from typing import Tuple
+import numpy as np
+from numpy.typing import NDArray
+
+from job_shop_lib.exceptions import ValidationError
+
+
+def generate_duration_matrix(
+    num_jobs: int, num_machines: int, duration_range: Tuple[int, int]
+) -> NDArray[np.int32]:
+    """Generates a duration matrix.
+
+    Args:
+        num_jobs: The number of jobs.
+        num_machines: The number of machines.
+        duration_range: The range of the duration values.
+
+    Returns:
+        A duration matrix with shape (num_jobs, num_machines).
+    """
+    if duration_range[0] > duration_range[1]:
+        raise ValidationError(
+            "The lower bound of the duration range must be less than or equal "
+            "to the upper bound."
+        )
+    if num_jobs <= 0:
+        raise ValidationError("The number of jobs must be greater than 0.")
+    if num_machines <= 0:
+        raise ValidationError("The number of machines must be greater than 0.")
+
+    return np.random.randint(
+        duration_range[0],
+        duration_range[1] + 1,
+        size=(num_jobs, num_machines),
+        dtype=np.int32,
+    )
+
+
+def generate_machine_matrix_with_recirculation(
+    num_jobs: int, num_machines: int
+) -> NDArray[np.int32]:
+    """Generate a machine matrix with recirculation.
+
+    Args:
+        num_jobs: The number of jobs.
+        num_machines: The number of machines.
+
+    Returns:
+        A machine matrix with recirculation with shape (num_machines,
+        num_jobs).
+    """
+    if num_jobs <= 0:
+        raise ValidationError("The number of jobs must be greater than 0.")
+    if num_machines <= 0:
+        raise ValidationError("The number of machines must be greater than 0.")
+    num_machines_is_correct = False
+    while not num_machines_is_correct:
+        machine_matrix: np.ndarray = np.random.randint(
+            0, num_machines, size=(num_machines, num_jobs)
+        )
+        num_machines_is_correct = (
+            len(np.unique(machine_matrix)) == num_machines
+        )
+
+    return machine_matrix
+
+
+def generate_machine_matrix_without_recirculation(
+    num_jobs: int, num_machines: int
+) -> NDArray[np.int32]:
+    """Generate a machine matrix without recirculation.
+
+    Args:
+        num_jobs: The number of jobs.
+        num_machines: The number of machines.
+
+    Returns:
+        A machine matrix without recirculation.
+    """
+    if num_jobs <= 0:
+        raise ValidationError("The number of jobs must be greater than 0.")
+    if num_machines <= 0:
+        raise ValidationError("The number of machines must be greater than 0.")
+    # Start with an arange repeated:
+    # m1: [0, 1, 2]
+    # m2: [0, 1, 2]
+    # m3: [0, 1, 2]
+    machine_matrix = np.tile(
+        np.arange(num_machines).reshape(1, num_machines),
+        (num_jobs, 1),
+    )
+    # Shuffle the columns:
+    machine_matrix = np.apply_along_axis(
+        np.random.permutation, 1, machine_matrix
+    )
+    return machine_matrix
+
+
+if __name__ == "__main__":
+
+    NUM_JOBS = 3
+    NUM_MACHINES = 3
+    DURATION_RANGE = (1, 10)
+
+    duration_matrix = generate_duration_matrix(
+        num_jobs=NUM_JOBS,
+        num_machines=NUM_MACHINES,
+        duration_range=DURATION_RANGE,
+    )
+    print(duration_matrix)
+
+    machine_matrix_with_recirculation = (
+        generate_machine_matrix_with_recirculation(
+            num_jobs=NUM_JOBS, num_machines=NUM_MACHINES
+        )
+    )
+    print(machine_matrix_with_recirculation)
+
+    machine_matrix_without_recirculation = (
+        generate_machine_matrix_without_recirculation(
+            num_jobs=NUM_JOBS, num_machines=NUM_MACHINES
+        )
+    )
+    print(machine_matrix_without_recirculation)

job_shop_lib/graphs/__init__.py

@@ -25,10 +25,10 @@ from job_shop_lib.graphs._build_disjunctive_graph import (
     add_source_sink_nodes,
     add_source_sink_edges,
 )
-from job_shop_lib.graphs._build_agent_task_graph import (
-    build_agent_task_graph,
-    build_complete_agent_task_graph,
-    build_agent_task_graph_with_jobs,
+from job_shop_lib.graphs._build_resource_task_graphs import (
+    build_resource_task_graph,
+    build_complete_resource_task_graph,
+    build_resource_task_graph_with_jobs,
     add_same_job_operations_edges,
     add_machine_nodes,
     add_operation_machine_edges,
@@ -52,9 +52,9 @@ __all__ = [
     "add_conjunctive_edges",
     "add_source_sink_nodes",
     "add_source_sink_edges",
-    "build_agent_task_graph",
-    "build_complete_agent_task_graph",
-    "build_agent_task_graph_with_jobs",
+    "build_resource_task_graph",
+    "build_complete_resource_task_graph",
+    "build_resource_task_graph_with_jobs",
     "add_same_job_operations_edges",
     "add_machine_nodes",
     "add_operation_machine_edges",

job_shop_lib/graphs/{_build_agent_task_graph.py → _build_resource_task_graphs.py}

@@ -1,16 +1,13 @@
-"""Contains helper functions to build the agent-task graph or one of
-its generalizations from a job shop instance.
+"""Contains helper functions to build the resource-task graphs from a job shop
+instance.
 
-The agent-task graph was introduced by Junyoung Park et al. (2021).
+The agent-task graph (renamed to resource-task graph) was introduced by
+Junyoung Park et al. (2021).
 In contrast to the disjunctive graph, instead of connecting operations that
 share the same resources directly by disjunctive edges, operation nodes are
 connected with machine ones. All machine nodes are connected between them, and
 all operation nodes from the same job are connected by non-directed edges too.
 
-We also support a generalization of this approach by the addition of job nodes
-and a global node. Job nodes are connected to all operation nodes of the same
-job, and the global node is connected to all machine and job nodes.
-
 References:
 - Junyoung Park, Sanjar Bakhtiyar, and Jinkyoo Park. Schedulenet: Learn to
   solve multi-agent scheduling problems with reinforcement learning. ArXiv,
@@ -23,11 +20,13 @@ from job_shop_lib import JobShopInstance
 from job_shop_lib.graphs import JobShopGraph, NodeType, Node
 
 
-def build_complete_agent_task_graph(instance: JobShopInstance) -> JobShopGraph:
-    """Builds the agent-task graph of the instance with job and global nodes.
+def build_complete_resource_task_graph(
+    instance: JobShopInstance,
+) -> JobShopGraph:
+    """Builds the resource-task graph of the instance with job and global
+    nodes.
 
-    The complete agent-task graph is a generalization of the agent-task graph
-    that includes job nodes and a global node.
+    The complete resource-task includes job nodes and a global node.
 
     Job nodes are connected to all operation nodes of the same job, and the
     global node is connected to all machine and job nodes.
@@ -38,10 +37,11 @@ def build_complete_agent_task_graph(instance: JobShopInstance) -> JobShopGraph:
 
     Args:
         instance:
-            The job shop instance in which the agent-task graph will be built.
+            The job shop instance in which the resource-task graph will be
+            built.
 
     Returns:
-        The complete agent-task graph of the instance.
+        The complete resource-task graph of the instance.
     """
     graph = JobShopGraph(instance)
 
@@ -58,23 +58,23 @@ def build_complete_agent_task_graph(instance: JobShopInstance) -> JobShopGraph:
     return graph
 
 
-def build_agent_task_graph_with_jobs(
+def build_resource_task_graph_with_jobs(
     instance: JobShopInstance,
 ) -> JobShopGraph:
-    """Builds the agent-task graph of the instance with job nodes.
+    """Builds the resource-task graph of the instance with job nodes.
 
-    The agent-task graph with job nodes is a generalization of the agent-task
-    graph that includes job nodes.
+    The resource-task graph that includes job nodes.
 
     Job nodes are connected to all operation nodes of the same job, and their
     are connected between them.
 
     Args:
         instance:
-            The job shop instance in which the agent-task graph will be built.
+            The job shop instance in which the resource-task graph will be
+            built.
 
     Returns:
-        The agent-task graph of the instance with job nodes.
+        The resource-task graph of the instance with job nodes.
     """
     graph = JobShopGraph(instance)
 
@@ -89,10 +89,11 @@ def build_agent_task_graph_with_jobs(
     return graph
 
 
-def build_agent_task_graph(instance: JobShopInstance) -> JobShopGraph:
-    """Builds the agent-task graph of the instance.
+def build_resource_task_graph(instance: JobShopInstance) -> JobShopGraph:
+    """Builds the resource-task graph of the instance.
 
-    The agent-task graph was introduced by Junyoung Park et al. (2021).
+    The JSSP resource-task graph representation was introduced by Junyoung
+    Park et al. (2021) (named agent-task graph in the original paper).
 
     In contrast to the disjunctive graph, instead of connecting operations
     that share the same resources directly by disjunctive edges, operation
@@ -103,10 +104,11 @@ def build_agent_task_graph(instance: JobShopInstance) -> JobShopGraph:
 
     Args:
         instance:
-            The job shop instance in which the agent-task graph will be built.
+            The job shop instance in which the resource-task graph will be
+            built.
 
     Returns:
-        The agent-task graph of the instance.
+        The resource-task graph of the instance.
     """
     graph = JobShopGraph(instance)