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

job_shop_lib/graphs/job_shop_graph.py

@@ -0,0 +1,159 @@
+"""Home of the `JobShopGraph` class."""
+
+import collections
+import networkx as nx
+
+from job_shop_lib import JobShopInstance, Operation
+from job_shop_lib.graphs import Node, NodeType
+
+
+NODE_ATTR = "node"
+
+
+class JobShopGraph:
+    """Data structure to represent a `JobShopInstance` as a 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.
+
+    Attributes:
+        instance:
+            The job shop instance encapsulated by this graph.
+        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:
+            A list of all nodes, encapsulated by the `Node` class, in the
+                graph.
+        nodes_by_type:
+            A dictionary categorizing nodes by their `NodeType`,
+                facilitating access to nodes of a particular type.
+        nodes_by_machine:
+            A nested list mapping each machine to its associated
+                operation nodes, aiding in machine-specific analysis.
+        nodes_by_job:
+            Similar to `nodes_by_machine`, but maps jobs to their
+                operation nodes, useful for job-specific traversal.
+    """
+
+    __slots__ = (
+        "instance",
+        "graph",
+        "nodes",
+        "nodes_by_type",
+        "nodes_by_machine",
+        "nodes_by_job",
+        "_next_node_id",
+    )
+
+    def __init__(self, instance: JobShopInstance):
+        """Initializes the graph with the given instance.
+
+        Nodes of type `OPERATION` are added to the graph based on the
+        operations of the instance.
+
+        Args:
+            instance:
+                The job shop instance that the graph represents.
+        """
+        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._add_operation_nodes()
+
+    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 get_operation_from_id(self, operation_id: int) -> Operation:
+        """Returns the operation with the given id."""
+        return self.nodes[operation_id].operation
+
+    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 `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 (Node): The node to be added to the graph.
+
+        Raises:
+            ValueError: If the node type is unsupported or if required
+            attributes for the node type are missing.
+
+        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
+
+        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: Node | int, v_of_edge: Node | int, **attr
+    ) -> None:
+        """Adds an edge to the graph.
+
+        Args:
+            u_of_edge: The source node of the edge. If it is a `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 `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:
+            ValueError: 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 ValueError(
+                "`u_of_edge` and `v_of_edge` must be in the graph."
+            )
+        self.graph.add_edge(u_of_edge, v_of_edge, **attr)

job_shop_lib/graphs/node.py

@@ -0,0 +1,147 @@
+"""Home of the `Node` class."""
+
+from job_shop_lib import Operation
+from job_shop_lib.graphs.constants import NodeType
+
+
+class Node:
+    """Data structure to represent a node in the `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:
+
+    ```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. It can be one of the following:
+            - NodeType.OPERATION
+            - NodeType.MACHINE
+            - NodeType.JOB
+            - NodeType.GLOBAL
+            ...
+        operation:
+            The operation of the node. It should be provided if the node_type
+            is NodeType.OPERATION.
+        machine_id:
+            The id of the machine of the node. It should be provided if the
+            node_type is NodeType.MACHINE.
+        job_id:
+            The id of the job of the node. It should be provided if the
+            node_type is NodeType.JOB.
+    """
+
+    __slots__ = "node_type", "_node_id", "_operation", "_machine_id", "_job_id"
+
+    def __init__(
+        self,
+        node_type: NodeType,
+        operation: Operation | None = None,
+        machine_id: int | None = None,
+        job_id: int | None = None,
+    ):
+        if node_type == NodeType.OPERATION and operation is None:
+            raise ValueError("Operation node must have an operation.")
+
+        if node_type == NodeType.MACHINE and machine_id is None:
+            raise ValueError("Machine node must have a machine_id.")
+
+        if node_type == NodeType.JOB and job_id is None:
+            raise ValueError("Job node must have a job_id.")
+
+        self.node_type = node_type
+        self._node_id: int | None = 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 ValueError("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 `OPERATION`.
+        """
+        if self._operation is None:
+            raise ValueError("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`.
+        """
+        if self._machine_id is None:
+            raise ValueError("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`.
+        """
+        if self._job_id is None:
+            raise ValueError("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/job_shop_instance.py

@@ -0,0 +1,355 @@
+"""Contains the `JobShopInstance` class."""
+
+from __future__ import annotations
+
+import os
+import functools
+from typing import Any
+
+from job_shop_lib import Operation
+
+
+class JobShopInstance:
+    """Data structure to store a Job Shop Scheduling Problem instance.
+
+    Additional attributes such as `num_jobs` or `num_machines` can be computed
+    from the instance and are cached for performance if they require expensive
+    computations.
+
+    Attributes:
+        jobs:
+            A list of lists of operations. Each list of operations represents
+            a job, and the operations are ordered by their position in the job.
+            The `job_id`, `position_in_job`, and `operation_id` attributes of
+            the operations are set when the instance is created.
+        name:
+            A string with the name of the instance.
+        metadata:
+            A dictionary with additional information about the instance.
+    """
+
+    def __init__(
+        self,
+        jobs: list[list[Operation]],
+        name: str = "JobShopInstance",
+        **metadata: Any,
+    ):
+        """Initializes the instance based on a list of lists of operations.
+
+        Args:
+            jobs:
+                A list of lists of operations. Each list of operations
+                represents a job, and the operations are ordered by their
+                position in the job. The `job_id`, `position_in_job`, and
+                `operation_id` attributes of the operations are set when the
+                instance is created.
+            name:
+                A string with the name of the instance.
+            **metadata:
+                Additional information about the instance.
+        """
+        self.jobs = jobs
+        self.set_operation_attributes()
+        self.name = name
+        self.metadata = metadata
+
+    def set_operation_attributes(self):
+        """Sets the job_id and position of each operation."""
+        operation_id = 0
+        for job_id, job in enumerate(self.jobs):
+            for position, operation in enumerate(job):
+                operation.job_id = job_id
+                operation.position_in_job = position
+                operation.operation_id = operation_id
+                operation_id += 1
+
+    @classmethod
+    def from_taillard_file(
+        cls,
+        file_path: os.PathLike | str | bytes,
+        encoding: str = "utf-8",
+        comment_symbol: str = "#",
+        name: str | None = None,
+        **metadata: Any,
+    ) -> JobShopInstance:
+        """Creates a JobShopInstance from a file following Taillard's format.
+
+        Args:
+            file_path:
+                A path-like object or string representing the path to the file.
+            encoding:
+                The encoding of the file.
+            comment_symbol:
+                A string representing the comment symbol used in the file.
+                Lines starting with this symbol are ignored.
+            name:
+                A string with the name of the instance. If not provided, the
+                name of the instance is set to the name of the file.
+            **metadata:
+                Additional information about the instance.
+
+        Returns:
+            A JobShopInstance object with the operations read from the file,
+            and the name and metadata provided.
+        """
+        with open(file_path, "r", encoding=encoding) as file:
+            lines = file.readlines()
+
+        first_non_comment_line_reached = False
+        jobs = []
+        for line in lines:
+            line = line.strip()
+            if line.startswith(comment_symbol):
+                continue
+            if not first_non_comment_line_reached:
+                first_non_comment_line_reached = True
+                continue
+
+            row = list(map(int, line.split()))
+            pairs = zip(row[::2], row[1::2])
+            operations = [
+                Operation(machines=machine_id, duration=duration)
+                for machine_id, duration in pairs
+            ]
+            jobs.append(operations)
+
+        if name is None:
+            name = os.path.basename(str(file_path))
+            if "." in name:
+                name = name.split(".")[0]
+        return cls(jobs=jobs, name=name, **metadata)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Returns a dictionary representation of the instance.
+
+        This representation is useful for saving the instance to a JSON file,
+        which is a more computer-friendly format than more traditional ones
+        like Taillard's.
+
+        Returns:
+        The returned dictionary has the following structure:
+        {
+            "name": self.name,
+            "duration_matrix": self.durations_matrix,
+            "machines_matrix": self.machines_matrix,
+            "metadata": self.metadata,
+        }
+        """
+        return {
+            "name": self.name,
+            "duration_matrix": self.durations_matrix,
+            "machines_matrix": self.machines_matrix,
+            "metadata": self.metadata,
+        }
+
+    @classmethod
+    def from_matrices(
+        cls,
+        duration_matrix: list[list[int]],
+        machines_matrix: list[list[list[int]]] | list[list[int]],
+        name: str = "JobShopInstance",
+        metadata: dict[str, Any] | None = None,
+    ) -> JobShopInstance:
+        """Creates a JobShopInstance from duration and machines matrices.
+
+        Args:
+            duration_matrix:
+                A list of lists of integers. The i-th list contains the
+                durations of the operations of the job with id i.
+            machines_matrix:
+            A list of lists of lists of integers if the
+                instance is flexible, or a list of lists of integers if the
+                instance is not flexible. The i-th list contains the machines
+                in which the operations of the job with id i can be processed.
+            name:
+                A string with the name of the instance.
+            metadata:
+                A dictionary with additional information about the instance.
+
+        Returns:
+            A JobShopInstance object.
+        """
+        jobs: list[list[Operation]] = [[] for _ in range(len(duration_matrix))]
+
+        num_jobs = len(duration_matrix)
+        for job_id in range(num_jobs):
+            num_operations = len(duration_matrix[job_id])
+            for position_in_job in range(num_operations):
+                duration = duration_matrix[job_id][position_in_job]
+                machines = machines_matrix[job_id][position_in_job]
+                jobs[job_id].append(
+                    Operation(duration=duration, machines=machines)
+                )
+
+        metadata = {} if metadata is None else metadata
+        return cls(jobs=jobs, name=name, **metadata)
+
+    def __repr__(self) -> str:
+        return (
+            f"JobShopInstance(name={self.name}, "
+            f"num_jobs={self.num_jobs}, num_machines={self.num_machines})"
+        )
+
+    def __eq__(self, other: Any) -> bool:
+        if not isinstance(other, JobShopInstance):
+            return False
+        return self.jobs == other.jobs
+
+    @property
+    def num_jobs(self) -> int:
+        """Returns the number of jobs in the instance."""
+        return len(self.jobs)
+
+    @functools.cached_property
+    def num_machines(self) -> int:
+        """Returns the number of machines in the instance.
+
+        Computed as the maximum machine id present in the instance plus one.
+        """
+        max_machine_id = -1
+        for job in self.jobs:
+            for operation in job:
+                max_machine_id = max(max_machine_id, *operation.machines)
+        return max_machine_id + 1
+
+    @functools.cached_property
+    def num_operations(self) -> int:
+        """Returns the number of operations in the instance."""
+        return sum(len(job) for job in self.jobs)
+
+    @functools.cached_property
+    def is_flexible(self) -> bool:
+        """Returns True if any operation has more than one machine."""
+        return any(
+            any(len(operation.machines) > 1 for operation in job)
+            for job in self.jobs
+        )
+
+    @functools.cached_property
+    def durations_matrix(self) -> list[list[int]]:
+        """Returns the duration matrix of the instance.
+
+        The duration of the operation with `job_id` i and `position_in_job` j
+        is stored in the i-th position of the j-th list of the returned matrix:
+
+        ```python
+        duration = instance.durations_matrix[i][j]
+        ```
+        """
+        return [[operation.duration for operation in job] for job in self.jobs]
+
+    @functools.cached_property
+    def machines_matrix(self) -> list[list[list[int]]] | list[list[int]]:
+        """Returns the machines matrix of the instance.
+
+        If the instance is flexible (i.e., if any operation has more than one
+        machine in which it can be processed), the returned matrix is a list of
+        lists of lists of integers.
+
+        Otherwise, the returned matrix is a list of lists of integers.
+
+        To access the machines of the operation with position i in the job
+        with id j, the following code must be used:
+
+        ```python
+        machines = instance.machines_matrix[j][i]
+        ```
+
+        """
+        if self.is_flexible:
+            return [
+                [operation.machines for operation in job] for job in self.jobs
+            ]
+        return [
+            [operation.machine_id for operation in job] for job in self.jobs
+        ]
+
+    @functools.cached_property
+    def operations_by_machine(self) -> list[list[Operation]]:
+        """Returns a list of lists of operations.
+
+        The i-th list contains the operations that can be processed in the
+        machine with id i.
+        """
+        operations_by_machine: list[list[Operation]] = [
+            [] for _ in range(self.num_machines)
+        ]
+        for job in self.jobs:
+            for operation in job:
+                for machine_id in operation.machines:
+                    operations_by_machine[machine_id].append(operation)
+
+        return operations_by_machine
+
+    @functools.cached_property
+    def max_duration(self) -> float:
+        """Returns the maximum duration of the instance.
+
+        Useful for normalizing the durations of the operations."""
+        return max(
+            max(operation.duration for operation in job) for job in self.jobs
+        )
+
+    @functools.cached_property
+    def max_duration_per_job(self) -> list[float]:
+        """Returns the maximum duration of each job in the instance.
+
+        The maximum duration of the job with id i is stored in the i-th
+        position of the returned list.
+
+        Useful for normalizing the durations of the operations.
+        """
+        return [max(op.duration for op in job) for job in self.jobs]
+
+    @functools.cached_property
+    def max_duration_per_machine(self) -> list[int]:
+        """Returns the maximum duration of each machine in the instance.
+
+        The maximum duration of the machine with id i is stored in the i-th
+        position of the returned list.
+
+        Useful for normalizing the durations of the operations.
+        """
+        max_duration_per_machine = [0] * self.num_machines
+        for job in self.jobs:
+            for operation in job:
+                for machine_id in operation.machines:
+                    max_duration_per_machine[machine_id] = max(
+                        max_duration_per_machine[machine_id],
+                        operation.duration,
+                    )
+        return max_duration_per_machine
+
+    @functools.cached_property
+    def job_durations(self) -> list[int]:
+        """Returns a list with the duration of each job in the instance.
+
+        The duration of a job is the sum of the durations of its operations.
+
+        The duration of the job with id i is stored in the i-th position of the
+        returned list.
+        """
+        return [sum(op.duration for op in job) for job in self.jobs]
+
+    @functools.cached_property
+    def machine_loads(self) -> list[int]:
+        """Returns the total machine load of each machine in the instance.
+
+        The total machine load of a machine is the sum of the durations of the
+        operations that can be processed in that machine.
+
+        The total machine load of the machine with id i is stored in the i-th
+        position of the returned list.
+        """
+        machine_times = [0] * self.num_machines
+        for job in self.jobs:
+            for operation in job:
+                for machine_id in operation.machines:
+                    machine_times[machine_id] += operation.duration
+
+        return machine_times
+
+    @functools.cached_property
+    def total_duration(self) -> int:
+        """Returns the sum of the durations of all operations in all jobs."""
+        return sum(self.job_durations)