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

job_shop_lib/generators/basic_generator.py

@@ -0,0 +1,197 @@
+"""Home of the `BasicGenerator` class."""
+
+import random
+from typing import Iterator
+
+from job_shop_lib import JobShopInstance, Operation
+
+
+class BasicGenerator:  # pylint: disable=too-many-instance-attributes
+    """Generates instances for job shop problems.
+
+    This class is designed to be versatile, enabling the creation of various
+    job shop instances without the need for multiple dedicated classes.
+
+    It supports customization of the number of jobs, machines, operation
+    durations, and more.
+
+    The class supports both single instance generation and iteration over
+    multiple instances, controlled by the `iteration_limit` parameter. It
+    implements the iterator protocol, allowing it to be used in a `for` loop.
+
+    Note:
+        When used as an iterator, the generator will produce instances until it
+        reaches the specified `iteration_limit`. If `iteration_limit` is None,
+        it will continue indefinitely.
+
+    Attributes:
+        num_jobs_range:
+            The range of the number of jobs to generate. If a single
+            int is provided, it is used as both the minimum and maximum.
+        duration_range:
+            The range of durations for each operation.
+        num_machines_range:
+            The range of the number of machines available. If a
+            single int is provided, it is used as both the minimum and maximum.
+        machines_per_operation:
+            Specifies how many machines each operation
+            can be assigned to. If a single int is provided, it is used for
+            all operations.
+        allow_less_jobs_than_machines:
+            If True, allows generating instances where the number of jobs is
+            less than the number of machines.
+        allow_recirculation:
+            If True, a job can visit the same machine more than once.
+        name_suffix:
+            A suffix to append to each instance's name for identification.
+        seed:
+            Seed for the random number generator to ensure reproducibility.
+    """
+
+    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),
+        allow_less_jobs_than_machines: bool = True,
+        allow_recirculation: bool = False,
+        machines_per_operation: int | tuple[int, int] = 1,
+        name_suffix: str = "classic_generated_instance",
+        seed: int | None = None,
+        iteration_limit: int | None = None,
+    ):
+        """Initializes the instance generator with the given parameters.
+
+        Args:
+            num_jobs:
+                The range of the number of jobs to generate.
+            num_machines:
+                The range of the number of machines available.
+            duration_range:
+                The range of durations for each operation.
+            allow_less_jobs_than_machines:
+                Allows instances with fewer jobs than machines.
+            allow_recirculation:
+                Allows jobs to visit the same machine multiple times.
+            machines_per_operation:
+                Specifies how many machines each operation can be assigned to.
+                If a single int is provided, it is used for all operations.
+            name_suffix:
+                Suffix for instance names.
+            seed:
+                Seed for the random number generator.
+            iteration_limit:
+                Maximum number of instances to generate in iteration mode.
+        """
+        if isinstance(num_jobs, int):
+            num_jobs = (num_jobs, num_jobs)
+
+        if isinstance(num_machines, int):
+            num_machines = (num_machines, num_machines)
+
+        if isinstance(machines_per_operation, int):
+            machines_per_operation = (
+                machines_per_operation,
+                machines_per_operation,
+            )
+
+        self.num_jobs_range = num_jobs
+        self.duration_range = duration_range
+        self.num_machines_range = num_machines
+        self.machines_per_operation = machines_per_operation
+
+        self.allow_less_jobs_than_machines = allow_less_jobs_than_machines
+        self.allow_recirculation = allow_recirculation
+        self.name_suffix = name_suffix
+
+        self._counter = 0
+        self._current_iteration = 0
+        self._iteration_limit = iteration_limit
+
+        if seed is not None:
+            random.seed(seed)
+
+    def generate(self) -> JobShopInstance:
+        """Generates a single job shop instance"""
+        num_jobs = random.randint(*self.num_jobs_range)
+
+        min_num_machines, max_num_machines = self.num_machines_range
+        if not self.allow_less_jobs_than_machines:
+            min_num_machines = min(num_jobs, max_num_machines)
+        num_machines = random.randint(min_num_machines, max_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._get_name())
+
+    def __iter__(self) -> Iterator[JobShopInstance]:
+        self._current_iteration = 0
+        return self
+
+    def __next__(self) -> JobShopInstance:
+        if (
+            self._iteration_limit is not None
+            and self._current_iteration >= self._iteration_limit
+        ):
+            raise StopIteration
+        self._current_iteration += 1
+        return self.generate()
+
+    def __len__(self) -> int:
+        if self._iteration_limit is None:
+            raise ValueError("Iteration limit is not set.")
+        return self._iteration_limit
+
+    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
+
+    def _get_name(self) -> str:
+        self._counter += 1
+        return f"{self.name_suffix}_{self._counter}"

job_shop_lib/graphs/__init__.py

@@ -0,0 +1,52 @@
+"""Package for graph related classes and functions."""
+
+from job_shop_lib.graphs.constants import EdgeType, NodeType
+from job_shop_lib.graphs.node import Node
+from job_shop_lib.graphs.job_shop_graph import JobShopGraph, NODE_ATTR
+from job_shop_lib.graphs.build_disjunctive_graph import (
+    build_disjunctive_graph,
+    add_disjunctive_edges,
+    add_conjunctive_edges,
+    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,
+    add_same_job_operations_edges,
+    add_machine_nodes,
+    add_operation_machine_edges,
+    add_machine_machine_edges,
+    add_job_nodes,
+    add_operation_job_edges,
+    add_global_node,
+    add_machine_global_edges,
+    add_job_global_edges,
+)
+
+
+__all__ = [
+    "EdgeType",
+    "NodeType",
+    "Node",
+    "JobShopGraph",
+    "NODE_ATTR",
+    "build_disjunctive_graph",
+    "add_disjunctive_edges",
+    "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",
+    "add_same_job_operations_edges",
+    "add_machine_nodes",
+    "add_operation_machine_edges",
+    "add_machine_machine_edges",
+    "add_job_nodes",
+    "add_operation_job_edges",
+    "add_global_node",
+    "add_machine_global_edges",
+    "add_job_global_edges",
+]

job_shop_lib/graphs/build_agent_task_graph.py

@@ -0,0 +1,209 @@
+"""Contains helper functions to build the agent-task graph or one of
+its generalizations from a job shop instance.
+
+The agent-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,
+abs/2106.03051, 2021.
+"""
+
+import itertools
+
+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.
+
+    The complete agent-task graph is a generalization of the agent-task graph
+    that 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.
+
+    This representation does not include edges between job or machine nodes
+    with the same type because they are connected indirectly by the global
+    node.
+
+    Args:
+        instance:
+            The job shop instance in which the agent-task graph will be built.
+
+    Returns:
+        The complete agent-task graph of the instance.
+    """
+    graph = JobShopGraph(instance)
+
+    add_machine_nodes(graph)
+    add_operation_machine_edges(graph)
+
+    add_job_nodes(graph)
+    add_operation_job_edges(graph)
+
+    add_global_node(graph)
+    add_machine_global_edges(graph)
+    add_job_global_edges(graph)
+
+    return graph
+
+
+def build_agent_task_graph_with_jobs(
+    instance: JobShopInstance,
+) -> JobShopGraph:
+    """Builds the agent-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.
+
+    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.
+
+    Returns:
+        The agent-task graph of the instance with job nodes.
+    """
+    graph = JobShopGraph(instance)
+
+    add_machine_nodes(graph)
+    add_operation_machine_edges(graph)
+    add_machine_machine_edges(graph)
+
+    add_job_nodes(graph)
+    add_operation_job_edges(graph)
+    add_job_job_edges(graph)
+
+    return graph
+
+
+def build_agent_task_graph(instance: JobShopInstance) -> JobShopGraph:
+    """Builds the agent-task graph of the instance.
+
+    The agent-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.
+
+    Args:
+        instance:
+            The job shop instance in which the agent-task graph will be built.
+
+    Returns:
+        The agent-task graph of the instance.
+    """
+    graph = JobShopGraph(instance)
+
+    add_machine_nodes(graph)
+    add_operation_machine_edges(graph)
+    add_machine_machine_edges(graph)
+
+    add_same_job_operations_edges(graph)
+
+    return graph
+
+
+# BUILDING BLOCKS
+# -----------------------------------------------------------------------------
+def add_same_job_operations_edges(graph: JobShopGraph) -> None:
+    """Adds edges between all operations of the same job."""
+    for job in graph.nodes_by_job:
+        for operation1, operation2 in itertools.combinations(job, 2):
+            graph.add_edge(operation1, operation2)
+            graph.add_edge(operation2, operation1)
+
+
+# MACHINE NODES
+# -------------
+def add_machine_nodes(graph: JobShopGraph) -> None:
+    """Adds a machine node for each machine in the instance."""
+    for machine_id in range(graph.instance.num_machines):
+        machine_node = Node(node_type=NodeType.MACHINE, machine_id=machine_id)
+        graph.add_node(machine_node)
+
+
+def add_operation_machine_edges(graph: JobShopGraph) -> None:
+    """Adds edges between operation and machine nodes."""
+    for machine_node in graph.nodes_by_type[NodeType.MACHINE]:
+        operation_nodes_in_machine = graph.nodes_by_machine[
+            machine_node.machine_id
+        ]
+        for operation_node in operation_nodes_in_machine:
+            graph.add_edge(machine_node, operation_node)
+            graph.add_edge(operation_node, machine_node)
+
+
+def add_machine_machine_edges(graph: JobShopGraph) -> None:
+    """Adds edges between all machine nodes."""
+    for machine1, machine2 in itertools.combinations(
+        graph.nodes_by_type[NodeType.MACHINE], 2
+    ):
+        graph.add_edge(machine1, machine2)
+        graph.add_edge(machine2, machine1)
+
+
+# JOB NODES
+# ---------
+def add_job_nodes(graph: JobShopGraph) -> None:
+    """Adds a job node for each job in the instance."""
+    for job_id in range(graph.instance.num_jobs):
+        job_node = Node(node_type=NodeType.JOB, job_id=job_id)
+        graph.add_node(job_node)
+
+
+def add_operation_job_edges(graph: JobShopGraph) -> None:
+    """Adds edges between operation and job nodes."""
+    for job_node in graph.nodes_by_type[NodeType.JOB]:
+        operation_nodes_in_job = graph.nodes_by_job[job_node.job_id]
+        for operation_node in operation_nodes_in_job:
+            graph.add_edge(job_node, operation_node)
+            graph.add_edge(operation_node, job_node)
+
+
+def add_job_job_edges(graph: JobShopGraph) -> None:
+    """Adds edges between all job nodes."""
+    for job1, job2 in itertools.combinations(
+        graph.nodes_by_type[NodeType.JOB], 2
+    ):
+        graph.add_edge(job1, job2)
+        graph.add_edge(job2, job1)
+
+
+# GLOBAL NODE
+# -----------
+def add_global_node(graph: JobShopGraph) -> None:
+    """Adds a global node to the graph."""
+    global_node = Node(node_type=NodeType.GLOBAL)
+    graph.add_node(global_node)
+
+
+def add_machine_global_edges(graph: JobShopGraph) -> None:
+    """Adds edges between machine and global nodes."""
+    global_node = graph.nodes_by_type[NodeType.GLOBAL][0]
+    for machine_node in graph.nodes_by_type[NodeType.MACHINE]:
+        graph.add_edge(global_node, machine_node)
+        graph.add_edge(machine_node, global_node)
+
+
+def add_job_global_edges(graph: JobShopGraph) -> None:
+    """Adds edges between job and global nodes."""
+    global_node = graph.nodes_by_type[NodeType.GLOBAL][0]
+    for job_node in graph.nodes_by_type[NodeType.JOB]:
+        graph.add_edge(global_node, job_node)
+        graph.add_edge(job_node, global_node)

job_shop_lib/graphs/build_disjunctive_graph.py

@@ -0,0 +1,78 @@
+"""Module for building the disjunctive graph of a job shop instance.
+
+The disjunctive graph is created by first adding nodes representing each
+operation in the jobs, along with two special nodes: a source $S$ and a sink
+$T$. Each operation node is linked to the next operation in its job sequence
+by **conjunctive edges**, forming a path from the source to the sink. These
+edges represent the order in which operations of a single job must be
+performed.
+
+Additionally, the graph includes **disjunctive edges** between operations
+that use the same machine but belong to different jobs. These edges are
+bidirectional, indicating that either of the connected operations can be
+performed first. The disjunctive edges thus represent the scheduling choices
+available: the order in which operations sharing a machine can be processed.
+Solving the Job Shop Scheduling problem involves choosing a direction for
+each disjunctive edge such that the overall processing time is minimized.
+"""
+
+import itertools
+
+from job_shop_lib import JobShopInstance
+from job_shop_lib.graphs import JobShopGraph, EdgeType, NodeType, Node
+
+
+def build_disjunctive_graph(instance: JobShopInstance) -> JobShopGraph:
+    graph = JobShopGraph(instance)
+    add_disjunctive_edges(graph)
+    add_conjunctive_edges(graph)
+    add_source_sink_nodes(graph)
+    add_source_sink_edges(graph)
+    return graph
+
+
+def add_disjunctive_edges(graph: JobShopGraph) -> None:
+    """Adds disjunctive edges to the graph."""
+
+    for machine in graph.nodes_by_machine:
+        for node1, node2 in itertools.combinations(machine, 2):
+            graph.add_edge(
+                node1,
+                node2,
+                type=EdgeType.DISJUNCTIVE,
+            )
+            graph.add_edge(
+                node2,
+                node1,
+                type=EdgeType.DISJUNCTIVE,
+            )
+
+
+def add_conjunctive_edges(graph: JobShopGraph) -> None:
+    """Adds conjunctive edges to the graph."""
+
+    for job_operations in graph.nodes_by_job:
+        for i in range(1, len(job_operations)):
+            graph.add_edge(
+                job_operations[i - 1],
+                job_operations[i],
+                type=EdgeType.CONJUNCTIVE,
+            )
+
+
+def add_source_sink_nodes(graph: JobShopGraph) -> None:
+    """Adds source and sink nodes to the graph."""
+    source = Node(node_type=NodeType.SOURCE)
+    sink = Node(node_type=NodeType.SINK)
+    graph.add_node(source)
+    graph.add_node(sink)
+
+
+def add_source_sink_edges(graph: JobShopGraph) -> None:
+    """Adds edges between source and sink nodes and operations."""
+    source = graph.nodes_by_type[NodeType.SOURCE][0]
+    sink = graph.nodes_by_type[NodeType.SINK][0]
+
+    for job_operations in graph.nodes_by_job:
+        graph.add_edge(source, job_operations[0], type=EdgeType.CONJUNCTIVE)
+        graph.add_edge(job_operations[-1], sink, type=EdgeType.CONJUNCTIVE)

job_shop_lib/graphs/constants.py

@@ -0,0 +1,21 @@
+"""Constants for the graph module."""
+
+import enum
+
+
+class EdgeType(enum.Enum):
+    """Enumeration of edge types."""
+
+    CONJUNCTIVE = 0
+    DISJUNCTIVE = 1
+
+
+class NodeType(enum.Enum):
+    """Enumeration of node types."""
+
+    OPERATION = enum.auto()
+    MACHINE = enum.auto()
+    JOB = enum.auto()
+    GLOBAL = enum.auto()
+    SOURCE = enum.auto()
+    SINK = enum.auto()