job-shop-lib 1.0.0a4__py3-none-any.whl → 1.0.0b1__py3-none-any.whl

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)
 

job_shop_lib/graphs/_job_shop_graph.py

@@ -1,5 +1,6 @@
 """Home of the `JobShopGraph` class."""
 
+from typing import List, Union, Dict
 import collections
 import networkx as nx
 
@@ -62,23 +63,23 @@ class JobShopGraph:
         self.graph = nx.DiGraph()
         self.instance = instance
 
-        self._nodes: list[Node] = []
-        self._nodes_by_type: dict[NodeType, list[Node]] = (
+        self._nodes: List[Node] = []
+        self._nodes_by_type: Dict[NodeType, List[Node]] = (
             collections.defaultdict(list)
         )
-        self._nodes_by_machine: list[list[Node]] = [
+        self._nodes_by_machine: List[List[Node]] = [
             [] for _ in range(instance.num_machines)
         ]
-        self._nodes_by_job: list[list[Node]] = [
+        self._nodes_by_job: List[List[Node]] = [
             [] for _ in range(instance.num_jobs)
         ]
         self._next_node_id = 0
-        self.removed_nodes: list[bool] = []
+        self.removed_nodes: List[bool] = []
         if add_operation_nodes:
             self.add_operation_nodes()
 
     @property
-    def nodes(self) -> list[Node]:
+    def nodes(self) -> List[Node]:
         """List of all nodes added to the graph.
 
         It may contain nodes that have been removed from the graph.
@@ -86,7 +87,7 @@ class JobShopGraph:
         return self._nodes
 
     @property
-    def nodes_by_type(self) -> dict[NodeType, list[Node]]:
+    def nodes_by_type(self) -> Dict[NodeType, List[Node]]:
         """Dictionary mapping node types to lists of nodes.
 
         It may contain nodes that have been removed from the graph.
@@ -94,7 +95,7 @@ class JobShopGraph:
         return self._nodes_by_type
 
     @property
-    def nodes_by_machine(self) -> list[list[Node]]:
+    def nodes_by_machine(self) -> List[List[Node]]:
         """List of lists mapping machine ids to operation nodes.
 
         It may contain nodes that have been removed from the graph.
@@ -102,7 +103,7 @@ class JobShopGraph:
         return self._nodes_by_machine
 
     @property
-    def nodes_by_job(self) -> list[list[Node]]:
+    def nodes_by_job(self) -> List[List[Node]]:
         """List of lists mapping job ids to operation nodes.
 
         It may contain nodes that have been removed from the graph.
@@ -163,7 +164,10 @@ class JobShopGraph:
                 self._nodes_by_machine[machine_id].append(node_for_adding)
 
     def add_edge(
-        self, u_of_edge: Node | int, v_of_edge: Node | int, **attr
+        self,
+        u_of_edge: Union[Node, int],
+        v_of_edge: Union[Node, int],
+        **attr,
     ) -> None:
         """Adds an edge to the graph.
 
@@ -177,7 +181,7 @@ class JobShopGraph:
             **attr: Additional attributes to be added to the edge.
 
         Raises:
-            JobShopLibError: If `u_of_edge` or `v_of_edge` are not in the
+            ValidationError: If `u_of_edge` or `v_of_edge` are not in the
                 graph.
         """
         if isinstance(u_of_edge, Node):
@@ -206,7 +210,7 @@ class JobShopGraph:
 
         self.graph.remove_nodes_from(isolated_nodes)
 
-    def is_removed(self, node: int | Node) -> bool:
+    def is_removed(self, node: Union[int, Node]) -> bool:
         """Returns whether the node is removed from the graph.
 
         Args:
@@ -218,7 +222,7 @@ class JobShopGraph:
             node = node.node_id
         return self.removed_nodes[node]
 
-    def non_removed_nodes(self) -> list[Node]:
+    def non_removed_nodes(self) -> List[Node]:
         """Returns the nodes that are not removed from the graph."""
         return [node for node in self._nodes if not self.is_removed(node)]
 

job_shop_lib/graphs/_node.py

@@ -1,5 +1,7 @@
 """Home of the `Node` class."""
 
+from typing import Optional
+
 from job_shop_lib import Operation
 from job_shop_lib.exceptions import (
     UninitializedAttributeError,
@@ -80,9 +82,9 @@ class Node:
     def __init__(
         self,
         node_type: NodeType,
-        operation: Operation | None = None,
-        machine_id: int | None = None,
-        job_id: int | None = None,
+        operation: Optional[Operation] = None,
+        machine_id: Optional[int] = None,
+        job_id: Optional[int] = None,
     ):
         if node_type == NodeType.OPERATION and operation is None:
             raise ValidationError("Operation node must have an operation.")
@@ -94,7 +96,7 @@ class Node:
             raise ValidationError("Job node must have a job_id.")
 
         self.node_type: NodeType = node_type
-        self._node_id: int | None = None
+        self._node_id: Optional[int] = None
 
         self._operation = operation
         self._machine_id = machine_id

job_shop_lib/graphs/graph_updaters/_residual_graph_updater.py

@@ -1,5 +1,7 @@
 """Home of the `ResidualGraphUpdater` class."""
 
+from typing import Optional, List
+
 from job_shop_lib import ScheduledOperation
 from job_shop_lib.exceptions import UninitializedAttributeError
 from job_shop_lib.graphs import NodeType, JobShopGraph
@@ -54,7 +56,7 @@ class ResidualGraphUpdater(GraphUpdater):
         remove_completed_machine_nodes: bool = True,
         remove_completed_job_nodes: bool = True,
     ):
-        self._is_completed_observer: None | IsCompletedObserver = None
+        self._is_completed_observer: Optional[IsCompletedObserver] = None
         self.remove_completed_job_nodes = remove_completed_job_nodes
         self.remove_completed_machine_nodes = remove_completed_machine_nodes
         self._initialize_is_completed_observer_attribute(dispatcher)
@@ -80,7 +82,7 @@ class ResidualGraphUpdater(GraphUpdater):
                     return False
             return True
 
-        feature_types: list[FeatureType] = []
+        feature_types: List[FeatureType] = []
         if self.remove_completed_machine_nodes:
             feature_types.append(FeatureType.MACHINES)
         if self.remove_completed_job_nodes: