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

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

@@ -1,20 +1,17 @@
-"""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 resource-task graph (originally called 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.
+  solve multi-agent scheduling problems with reinforcement learning. ArXiv,
+  abs/2106.03051, 2021.
 """
 
 import itertools
@@ -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/_constants.py

@@ -0,0 +1,38 @@
+"""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.
+
+    Nodes of type :class:`NodeType.OPERATION`, :class:`NodeType.MACHINE`, and
+    :class:`NodeType.JOB` have specific attributes associated with them in the
+    :class:`Node` class.
+
+    On the other hand, Nodes of type :class:`NodeType.GLOBAL`,
+    :class:`NodeType.SOURCE`, and :class:`NodeType.SINK` are used to represent
+    different concepts in the graph and accesing them, but they do not have
+    specific attributes associated with them.
+
+    .. tip::
+
+        While uncommon, it can be useful to extend this enumeration with
+        additional node types. This can be achieved using
+        `aenum <https://github.com/ethanfurman/aenum>`_'s
+        ``extend_enum`` (requires using Python 3.11+).
+    """
+
+    OPERATION = enum.auto()
+    MACHINE = enum.auto()
+    JOB = enum.auto()
+    GLOBAL = enum.auto()
+    SOURCE = enum.auto()
+    SINK = enum.auto()

job_shop_lib/graphs/_job_shop_graph.py

@@ -0,0 +1,320 @@
+"""Home of the `JobShopGraph` class."""
+
+from typing import List, Union, Dict
+import collections
+import networkx as nx
+
+from job_shop_lib import JobShopInstance
+from job_shop_lib.exceptions import ValidationError
+from job_shop_lib.graphs import Node, NodeType
+
+
+NODE_ATTR = "node"
+
+
+# pylint: disable=too-many-instance-attributes
+class JobShopGraph:
+    """Represents a :class:`JobShopInstance` as a heterogeneous directed graph.
+
+    Provides a comprehensive graph-based representation of a job shop
+    scheduling problem, utilizing the ``networkx`` library to model the complex
+    relationships between jobs, operations, and machines. This class transforms
+    the abstract scheduling problem into a directed graph, where various
+    entities (jobs, machines, and operations) are nodes, and the dependencies
+    (such as operation order within a job or machine assignment) are edges.
+
+    This transformation allows for the application of graph algorithms
+    to analyze and solve scheduling problems.
+
+    Args:
+        instance:
+            The job shop instance that the graph represents.
+        add_operation_nodes:
+            Whether to add nodes of type :class:`NodeType.OPERATION` to the
+            to the graph. If set to ``False``, the graph will be empty, and
+            operation nodes will need to be added manually.
+    """
+
+    __slots__ = {
+        "instance": "The job shop instance that the graph represents.",
+        "graph": (
+            "The directed graph representing the job shop, where nodes are "
+            "operations, machines, jobs, or abstract concepts like global, "
+            "source, and sink, with edges indicating dependencies."
+        ),
+        "_nodes": "List of all nodes added to the graph.",
+        "_nodes_by_type": "Dictionary mapping node types to lists of nodes.",
+        "_nodes_by_machine": (
+            "List of lists mapping machine ids to operation nodes."
+        ),
+        "_nodes_by_job": "List of lists mapping job ids to operation nodes.",
+        "_next_node_id": (
+            "The id to assign to the next node added to thegraph."
+        ),
+        "removed_nodes": (
+            "List of boolean values indicating whether a node has been "
+            "removed from the graph."
+        ),
+    }
+
+    def __init__(
+        self, instance: JobShopInstance, add_operation_nodes: bool = True
+    ):
+        self.graph = nx.DiGraph()
+        self.instance = instance
+
+        self._nodes: List[Node] = []
+        self._nodes_by_type: Dict[NodeType, List[Node]] = (
+            collections.defaultdict(list)
+        )
+        self._nodes_by_machine: List[List[Node]] = [
+            [] for _ in range(instance.num_machines)
+        ]
+        self._nodes_by_job: List[List[Node]] = [
+            [] for _ in range(instance.num_jobs)
+        ]
+        self._next_node_id = 0
+        self.removed_nodes: List[bool] = []
+        if add_operation_nodes:
+            self.add_operation_nodes()
+
+    @property
+    def nodes(self) -> List[Node]:
+        """List of all nodes added to the graph.
+
+        It may contain nodes that have been removed from the graph.
+        """
+        return self._nodes
+
+    @property
+    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.
+        """
+        return self._nodes_by_type
+
+    @property
+    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.
+        """
+        return self._nodes_by_machine
+
+    @property
+    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.
+        """
+        return self._nodes_by_job
+
+    @property
+    def num_edges(self) -> int:
+        """Number of edges in the graph."""
+        return self.graph.number_of_edges()
+
+    @property
+    def num_job_nodes(self) -> int:
+        """Number of job nodes in the graph."""
+        return len(self._nodes_by_type[NodeType.JOB])
+
+    def add_operation_nodes(self) -> None:
+        """Adds operation nodes to the graph."""
+        for job in self.instance.jobs:
+            for operation in job:
+                node = Node(node_type=NodeType.OPERATION, operation=operation)
+                self.add_node(node)
+
+    def add_node(self, node_for_adding: Node) -> None:
+        """Adds a node to the graph and updates relevant class attributes.
+
+        This method assigns a unique identifier to the node, adds it to the
+        graph, and updates the nodes list and the nodes_by_type dictionary. If
+        the node is of type :class:`NodeType.OPERATION`, it also updates
+        ``nodes_by_job`` and ``nodes_by_machine`` based on the operation's
+        job id and machine ids.
+
+        Args:
+            node_for_adding:
+                The node to be added to the graph.
+
+        Note:
+            This method directly modifies the graph attribute as well as
+            several other class attributes. Thus, adding nodes to the graph
+            should be done exclusively through this method to avoid
+            inconsistencies.
+        """
+        node_for_adding.node_id = self._next_node_id
+        self.graph.add_node(
+            node_for_adding.node_id, **{NODE_ATTR: node_for_adding}
+        )
+        self._nodes_by_type[node_for_adding.node_type].append(node_for_adding)
+        self._nodes.append(node_for_adding)
+        self._next_node_id += 1
+        self.removed_nodes.append(False)
+
+        if node_for_adding.node_type == NodeType.OPERATION:
+            operation = node_for_adding.operation
+            self._nodes_by_job[operation.job_id].append(node_for_adding)
+            for machine_id in operation.machines:
+                self._nodes_by_machine[machine_id].append(node_for_adding)
+
+    def add_edge(
+        self,
+        u_of_edge: Union[Node, int],
+        v_of_edge: Union[Node, int],
+        **attr,
+    ) -> None:
+        """Adds an edge to the graph.
+
+        It automatically determines the edge type based on the source and
+        destination nodes unless explicitly provided in the ``attr`` argument
+        via the ``type`` key. The edge type is a tuple of strings:
+        ``(source_node_type, "to", destination_node_type)``.
+
+        Args:
+            u_of_edge:
+                The source node of the edge. If it is a :class:`Node`, its
+                ``node_id`` is used as the source. Otherwise, it is assumed to
+                be the ``node_id`` of the source.
+            v_of_edge:
+                The destination node of the edge. If it is a :class:`Node`,
+                its ``node_id`` is used as the destination. Otherwise, it
+                is assumed to be the ``node_id`` of the destination.
+            **attr:
+                Additional attributes to be added to the edge.
+
+        Raises:
+            ValidationError: If ``u_of_edge`` or ``v_of_edge`` are not in the
+                graph.
+        """
+        if isinstance(u_of_edge, Node):
+            u_of_edge = u_of_edge.node_id
+        if isinstance(v_of_edge, Node):
+            v_of_edge = v_of_edge.node_id
+        if u_of_edge not in self.graph or v_of_edge not in self.graph:
+            raise ValidationError(
+                "`u_of_edge` and `v_of_edge` must be in the graph."
+            )
+        edge_type = attr.pop("type", None)
+        if edge_type is None:
+            u_node = self.nodes[u_of_edge]
+            v_node = self.nodes[v_of_edge]
+            edge_type = (
+                u_node.node_type.name.lower(),
+                "to",
+                v_node.node_type.name.lower(),
+            )
+        self.graph.add_edge(u_of_edge, v_of_edge, type=edge_type, **attr)
+
+    def remove_node(self, node_id: int) -> None:
+        """Removes a node from the graph and the isolated nodes that result
+        from the removal.
+
+        Args:
+            node_id:
+                The id of the node to remove.
+        """
+        self.graph.remove_node(node_id)
+        self.removed_nodes[node_id] = True
+
+    def remove_isolated_nodes(self) -> None:
+        """Removes isolated nodes from the graph."""
+        isolated_nodes = list(nx.isolates(self.graph))
+        for isolated_node in isolated_nodes:
+            self.removed_nodes[isolated_node] = True
+
+        self.graph.remove_nodes_from(isolated_nodes)
+
+    def is_removed(self, node: Union[int, Node]) -> bool:
+        """Returns whether the node is removed from the graph.
+
+        Args:
+            node:
+                The node to check. If it is a ``Node``, its `node_id` is used
+                as the node to check. Otherwise, it is assumed to be the
+                ``node_id`` of the node to check.
+        """
+        if isinstance(node, Node):
+            node = node.node_id
+        return self.removed_nodes[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)]
+
+    def get_machine_node(self, machine_id: int) -> Node:
+        """Returns the node representing the machine with the given id.
+
+        Args:
+            machine_id: The id of the machine.
+
+        Returns:
+            The node representing the machine with the given id.
+        """
+        return self.get_node_by_type_and_id(
+            NodeType.MACHINE, machine_id, "machine_id"
+        )
+
+    def get_job_node(self, job_id: int) -> Node:
+        """Returns the node representing the job with the given id.
+
+        Args:
+            job_id: The id of the job.
+
+        Returns:
+            The node representing the job with the given id.
+        """
+        return self.get_node_by_type_and_id(NodeType.JOB, job_id, "job_id")
+
+    def get_operation_node(self, operation_id: int) -> Node:
+        """Returns the node representing the operation with the given id.
+
+        Args:
+            operation_id: The id of the operation.
+
+        Returns:
+            The node representing the operation with the given id.
+        """
+        return self.get_node_by_type_and_id(
+            NodeType.OPERATION, operation_id, "operation.operation_id"
+        )
+
+    def get_node_by_type_and_id(
+        self, node_type: NodeType, node_id: int, id_attr: str
+    ) -> Node:
+        """Generic method to get a node by type and id.
+
+        Args:
+            node_type:
+                The type of the node.
+            node_id:
+                The id of the node.
+            id_attr:
+                The attribute name to compare the id. Can be nested like
+                'operation.operation_id'.
+
+        Returns:
+            The node with the given id.
+        """
+
+        def get_nested_attr(obj, attr_path: str):
+            """Helper function to get nested attribute."""
+            attrs = attr_path.split(".")
+            for attr in attrs:
+                obj = getattr(obj, attr)
+            return obj
+
+        nodes = self._nodes_by_type[node_type]
+        if node_id < len(nodes):
+            node = nodes[node_id]
+            if get_nested_attr(node, id_attr) == node_id:
+                return node
+
+        for node in nodes:
+            if get_nested_attr(node, id_attr) == node_id:
+                return node
+
+        raise ValidationError(f"No node found with node.{id_attr}={node_id}")

job_shop_lib/graphs/_node.py

@@ -0,0 +1,182 @@
+"""Home of the `Node` class."""
+
+from typing import Optional
+
+from job_shop_lib import Operation
+from job_shop_lib.exceptions import (
+    UninitializedAttributeError,
+    ValidationError,
+)
+from job_shop_lib.graphs._constants import NodeType
+
+
+class Node:
+    """Represents a node in the :class:`JobShopGraph`.
+
+    A node is hashable by its id. The id is assigned when the node is added to
+    the graph. The id must be unique for each node in the graph, and should be
+    used to identify the node in the networkx graph.
+
+    Depending on the type of the node, it can have different attributes. The
+    following table shows the attributes of each type of node:
+
+    +----------------+---------------------+
+    | Node Type      | Required Attribute  |
+    +================+=====================+
+    | OPERATION      | ``operation``       |
+    +----------------+---------------------+
+    | MACHINE        | ``machine_id``      |
+    +----------------+---------------------+
+    | JOB            | ``job_id``          |
+    +----------------+---------------------+
+
+    In terms of equality, two nodes are equal if they have the same id.
+    Additionally, one node is equal to an integer if the integer is equal to
+    its id. It is also hashable by its id.
+
+    This allows for using the node as a key in a dictionary, at the same time
+    we can use its id to index that dictionary. Example:
+
+    .. code-block:: python
+
+        node = Node(NodeType.SOURCE)
+        node.node_id = 1
+        graph = {node: "some value"}
+        print(graph[node])  # "some value"
+        print(graph[1])  # "some value"
+
+    Args:
+        node_type:
+            The type of the node. See :class:`NodeType` for theavailable types.
+        operation:
+            The operation of the node. Required if ``node_type`` is
+            :attr:`NodeType.OPERATION`.
+        machine_id:
+            The id of the machine. Required if ``node_type`` is
+            :attr:`NodeType.MACHINE`.
+        job_id:
+            The id of the job. Required if ``node_type`` is
+            :attr:`NodeType.JOB`.
+
+    Raises:
+        ValidationError:
+            If the ``node_type`` is :attr:`NodeType.OPERATION`,
+            :attr:`NodeType.MACHINE`, or :attr:`NodeType.JOB` and the
+            corresponding ``operation``, ``machine_id``, or ``job_id`` is
+            ``None``, respectively.
+
+    """
+
+    __slots__ = {
+        "node_type": "The type of the node.",
+        "_node_id": "Unique identifier for the node.",
+        "_operation": (
+            "The operation associated with the node."
+        ),
+        "_machine_id": (
+            "The machine ID associated with the node."
+        ),
+        "_job_id": "The job ID associated with the node.",
+    }
+
+    def __init__(
+        self,
+        node_type: NodeType,
+        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.")
+
+        if node_type == NodeType.MACHINE and machine_id is None:
+            raise ValidationError("Machine node must have a machine_id.")
+
+        if node_type == NodeType.JOB and job_id is None:
+            raise ValidationError("Job node must have a job_id.")
+
+        self.node_type: NodeType = node_type
+        self._node_id: Optional[int] = None
+
+        self._operation = operation
+        self._machine_id = machine_id
+        self._job_id = job_id
+
+    @property
+    def node_id(self) -> int:
+        """Returns a unique identifier for the node."""
+        if self._node_id is None:
+            raise UninitializedAttributeError(
+                "Node has not been assigned an id."
+            )
+        return self._node_id
+
+    @node_id.setter
+    def node_id(self, value: int) -> None:
+        self._node_id = value
+
+    @property
+    def operation(self) -> Operation:
+        """Returns the operation of the node.
+
+        This property is mandatory for nodes of type
+        :class:`NodeType.OPERATION`.
+
+        Raises:
+            UninitializedAttributeError: If the node has no operation.
+        """
+        if self._operation is None:
+            raise UninitializedAttributeError("Node has no operation.")
+        return self._operation
+
+    @property
+    def machine_id(self) -> int:
+        """Returns the `machine_id` of the node.
+
+        This property is mandatory for nodes of type `MACHINE`.
+
+        Raises:
+            UninitializedAttributeError: If the node has no ``machine_id``.
+        """
+        if self._machine_id is None:
+            raise UninitializedAttributeError("Node has no ``machine_id``.")
+        return self._machine_id
+
+    @property
+    def job_id(self) -> int:
+        """Returns the `job_id` of the node.
+
+        This property is mandatory for nodes of type `JOB`.
+
+        Raises:
+            UninitializedAttributeError: If the node has no `job_id`.
+        """
+        if self._job_id is None:
+            raise UninitializedAttributeError("Node has no `job_id`.")
+        return self._job_id
+
+    def __hash__(self) -> int:
+        return self.node_id
+
+    def __eq__(self, __value: object) -> bool:
+        if isinstance(__value, Node):
+            __value = __value.node_id
+        return self.node_id == __value
+
+    def __repr__(self) -> str:
+        if self.node_type == NodeType.OPERATION:
+            return (
+                f"Node(node_type={self.node_type.name}, id={self._node_id}, "
+                f"operation={self.operation})"
+            )
+        if self.node_type == NodeType.MACHINE:
+            return (
+                f"Node(node_type={self.node_type.name}, id={self._node_id}, "
+                f"machine_id={self._machine_id})"
+            )
+        if self.node_type == NodeType.JOB:
+            return (
+                f"Node(node_type={self.node_type.name}, id={self._node_id}, "
+                f"job_id={self._job_id})"
+            )
+        return f"Node(node_type={self.node_type.name}, id={self._node_id})"

job_shop_lib/graphs/graph_updaters/__init__.py

@@ -0,0 +1,26 @@
+"""Contains classes and functions for updating the graph representation of the
+job shop scheduling problem.
+
+Currently, the following classes and utilities are available:
+
+.. autosummary::
+
+    GraphUpdater
+    ResidualGraphUpdater
+    DisjunctiveGraphUpdater
+    remove_completed_operations
+
+"""
+
+from ._graph_updater import GraphUpdater
+from ._utils import remove_completed_operations
+from ._residual_graph_updater import ResidualGraphUpdater
+from ._disjunctive_graph_updater import DisjunctiveGraphUpdater
+
+
+__all__ = [
+    "GraphUpdater",
+    "remove_completed_operations",
+    "ResidualGraphUpdater",
+    "DisjunctiveGraphUpdater",
+]