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

job_shop_lib/operation.py

@@ -0,0 +1,120 @@
+"""Home of the `Operation` class."""
+
+from __future__ import annotations
+
+
+class Operation:
+    """Stores machine and duration information for a job operation.
+
+    Note:
+        To increase performance, some solvers such as the CP-SAT solver use
+        only integers to represent the operation's attributes. Should a
+        problem involve operations with non-integer durations, it would be
+        necessary to multiply all durations by a sufficiently large integer so
+        that every duration is an integer.
+
+    Attributes:
+        machines: A list of machine ids that can perform the operation.
+        duration: The time it takes to perform the operation.
+    """
+
+    __slots__ = (
+        "machines",
+        "duration",
+        "_job_id",
+        "_position_in_job",
+        "_operation_id",
+    )
+
+    def __init__(self, machines: int | list[int], duration: int):
+        """Initializes the object with the given machines and duration.
+
+        Args:
+            machines: A list of machine ids that can perform the operation. If
+                only one machine can perform the operation, it can be passed as
+                an integer.
+            duration: The time it takes to perform the operation.
+        """
+        self.machines = [machines] if isinstance(machines, int) else machines
+        self.duration = duration
+
+        # Defined outside the class by the JobShopInstance class:
+        self._job_id: int | None = None
+        self._position_in_job: int | None = None
+        self._operation_id: int | None = None
+
+    @property
+    def machine_id(self) -> int:
+        """Returns the id of the machine associated with the operation.
+
+        Raises:
+            ValueError: If the operation has multiple machines in its list.
+        """
+        if len(self.machines) > 1:
+            raise ValueError("Operation has multiple machines.")
+        return self.machines[0]
+
+    @property
+    def job_id(self) -> int:
+        """Returns the id of the job that the operation belongs to."""
+        if self._job_id is None:
+            raise ValueError("Operation has no job_id.")
+        return self._job_id
+
+    @job_id.setter
+    def job_id(self, value: int) -> None:
+        self._job_id = value
+
+    @property
+    def position_in_job(self) -> int:
+        """Returns the position (starting at zero) of the operation in the
+        job.
+
+        Raises:
+            ValueError: If the operation has no position_in_job.
+        """
+        if self._position_in_job is None:
+            raise ValueError("Operation has no position_in_job.")
+        return self._position_in_job
+
+    @position_in_job.setter
+    def position_in_job(self, value: int) -> None:
+        self._position_in_job = value
+
+    @property
+    def operation_id(self) -> int:
+        """Returns the id of the operation.
+
+        The operation id is unique within a job shop instance and should
+        be set by the JobShopInstance class.
+
+        It starts at 0 and is incremented by 1 for each operation in the
+        instance.
+
+        Raises:
+            ValueError: If the operation has no id.
+        """
+        if self._operation_id is None:
+            raise ValueError("Operation has no id.")
+        return self._operation_id
+
+    @operation_id.setter
+    def operation_id(self, value: int) -> None:
+        self._operation_id = value
+
+    def __hash__(self) -> int:
+        return hash(self.operation_id)
+
+    def __eq__(self, __value: object) -> bool:
+        if isinstance(__value, Operation):
+            return self.operation_id == __value.operation_id
+        return False
+
+    def __repr__(self) -> str:
+        machines = (
+            self.machines[0] if len(self.machines) == 1 else self.machines
+        )
+        return (
+            f"O(m={machines}, d={self.duration}, "
+            f"j={self.job_id}, p={self.position_in_job})"
+        )

job_shop_lib/schedule.py

@@ -0,0 +1,180 @@
+"""Home of the `Schedule` class."""
+
+from job_shop_lib import ScheduledOperation, JobShopInstance
+
+
+class Schedule:
+    """Data structure to store a schedule for a `JobShopInstance` object.
+
+    Attributes:
+        instance:
+            The `JobShopInstance` object that the schedule is for.
+        schedule:
+            A list of lists of `ScheduledOperation` objects. Each list of
+            `ScheduledOperation` objects represents the order of operations
+            on a machine.
+        metadata:
+            A dictionary with additional information about the schedule. It
+            can be used to store information about the algorithm that generated
+            the schedule, for example.
+    """
+
+    __slots__ = (
+        "instance",
+        "_schedule",
+        "metadata",
+    )
+
+    def __init__(
+        self,
+        instance: JobShopInstance,
+        schedule: list[list[ScheduledOperation]] | None = None,
+        **metadata,
+    ):
+        """Initializes the object with the given instance and schedule.
+
+        Args:
+            instance:
+                The `JobShopInstance` object that the schedule is for.
+            schedule:
+                A list of lists of `ScheduledOperation` objects. Each list of
+                `ScheduledOperation` objects represents the order of operations
+                on a machine. If not provided, the schedule is initialized as
+                an empty schedule.
+            **metadata:
+                Additional information about the schedule.
+        """
+        if schedule is None:
+            schedule = [[] for _ in range(instance.num_machines)]
+
+        Schedule.check_schedule(schedule)
+
+        self.instance = instance
+        self._schedule = schedule
+        self.metadata = metadata
+
+    def __repr__(self) -> str:
+        return str(self.schedule)
+
+    @property
+    def schedule(self) -> list[list[ScheduledOperation]]:
+        """Returns the schedule attribute."""
+        return self._schedule
+
+    @schedule.setter
+    def schedule(self, new_schedule: list[list[ScheduledOperation]]):
+        Schedule.check_schedule(new_schedule)
+        self._schedule = new_schedule
+
+    @property
+    def num_scheduled_operations(self) -> int:
+        """Returns the number of operations that have been scheduled."""
+        return sum(len(machine_schedule) for machine_schedule in self.schedule)
+
+    def reset(self):
+        """Resets the schedule to an empty state."""
+        self.schedule = [[] for _ in range(self.instance.num_machines)]
+
+    def makespan(self) -> int:
+        """Returns the makespan of the schedule.
+
+        The makespan is the time at which all operations are completed.
+        """
+        max_end_time = 0
+        for machine_schedule in self.schedule:
+            if machine_schedule:
+                max_end_time = max(max_end_time, machine_schedule[-1].end_time)
+        return max_end_time
+
+    def is_complete(self) -> bool:
+        """Returns True if all operations have been scheduled."""
+        return self.num_scheduled_operations == self.instance.num_operations
+
+    def add(self, scheduled_operation: ScheduledOperation):
+        """Adds a new `ScheduledOperation` to the schedule.
+
+        Args:
+            scheduled_operation:
+                The `ScheduledOperation` to add to the schedule.
+
+        Raises:
+            ValueError: If the start time of the new operation is before the
+                end time of the last operation on the same machine. In favor of
+                performance, this method does not checks precedence
+                constraints.
+        """
+        self._check_start_time_of_new_operation(scheduled_operation)
+        self.schedule[scheduled_operation.machine_id].append(
+            scheduled_operation
+        )
+
+    def _check_start_time_of_new_operation(
+        self,
+        new_operation: ScheduledOperation,
+    ):
+        is_first_operation = not self.schedule[new_operation.machine_id]
+        if is_first_operation:
+            return
+
+        last_operation = self.schedule[new_operation.machine_id][-1]
+        self._check_start_time(new_operation, last_operation)
+
+    @staticmethod
+    def _check_start_time(
+        scheduled_operation: ScheduledOperation,
+        previous_operation: ScheduledOperation,
+    ):
+        """Raises a ValueError if the start time of the new operation is before
+        the end time of the last operation on the same machine."""
+
+        if previous_operation.end_time <= scheduled_operation.start_time:
+            return
+
+        raise ValueError(
+            "Operation cannot be scheduled before the last operation on "
+            "the same machine: end time of last operation "
+            f"({previous_operation.end_time}) > start time of new operation "
+            f"({scheduled_operation.start_time})."
+        )
+
+    @staticmethod
+    def check_schedule(schedule: list[list[ScheduledOperation]]):
+        """Checks if a schedule is valid and raises a ValueError if it is not.
+
+        A schedule is considered invalid if:
+            - A `ScheduledOperation` has a machine id that does not match the
+              machine id of the machine schedule (the list of
+              `ScheduledOperation` objects) that it belongs to.
+            - The start time of a `ScheduledOperation` is before the end time
+              of the last operation on the same machine.
+
+        Args:
+            schedule:
+                The schedule (a list of lists of `ScheduledOperation` objects)
+                to check.
+
+        Raises:
+            ValueError: If the schedule is invalid.
+        """
+        for machine_id, scheduled_operations in enumerate(schedule):
+            for i, scheduled_operation in enumerate(scheduled_operations):
+                if scheduled_operation.machine_id != machine_id:
+                    raise ValueError(
+                        "The machine id of the scheduled operation "
+                        f"({ScheduledOperation.machine_id}) does not match "
+                        f"the machine id of the machine schedule ({machine_id}"
+                        f"). Index of the operation: [{machine_id}][{i}]."
+                    )
+
+                if i == 0:
+                    continue
+
+                Schedule._check_start_time(
+                    scheduled_operation, scheduled_operations[i - 1]
+                )
+
+    def __eq__(self, value: object) -> bool:
+        if not isinstance(value, Schedule):
+            return False
+
+        return self.schedule == value.schedule

job_shop_lib/scheduled_operation.py

@@ -0,0 +1,97 @@
+"""Home of the `ScheduledOperation` class."""
+
+from job_shop_lib import Operation
+
+
+class ScheduledOperation:
+    """Data structure to store a scheduled operation.
+
+    Attributes:
+        operation:
+            The `Operation` object that is scheduled.
+        start_time:
+            The time at which the operation is scheduled to start.
+        machine_id:
+            The id of the machine on which the operation is scheduled.
+    """
+
+    __slots__ = ("operation", "start_time", "_machine_id")
+
+    def __init__(self, operation: Operation, start_time: int, machine_id: int):
+        """Initializes the object with the given operation, start time, and
+        machine id.
+
+        Args:
+            operation:
+                The `Operation` object that is scheduled.
+            start_time:
+                The time at which the operation is scheduled to start.
+            machine_id:
+                The id of the machine on which the operation is scheduled.
+
+        Raises:
+            ValueError:
+                If the machine_id is not valid for the operation.
+        """
+        self.operation = operation
+        self.start_time = start_time
+        self._machine_id = machine_id
+        self.machine_id = machine_id  # Validate machine_id
+
+    @property
+    def machine_id(self) -> int:
+        """Returns the id of the machine on which the operation has been
+        scheduled."""
+        return self._machine_id
+
+    @machine_id.setter
+    def machine_id(self, value: int):
+        if value not in self.operation.machines:
+            raise ValueError(
+                f"Operation cannot be scheduled on machine {value}. "
+                f"Valid machines are {self.operation.machines}."
+            )
+        self._machine_id = value
+
+    @property
+    def job_id(self) -> int:
+        """Returns the id of the job that the operation belongs to.
+
+        Raises:
+            ValueError: If the operation has no job_id.
+        """
+
+        if self.operation.job_id is None:
+            raise ValueError("Operation has no job_id.")
+        return self.operation.job_id
+
+    @property
+    def position(self) -> int:
+        """Returns the position (starting at zero) of the operation in the job.
+
+        Raises:
+            ValueError: If the operation has no position_in_job.
+        """
+        if self.operation.position_in_job is None:
+            raise ValueError("Operation has no position.")
+        return self.operation.position_in_job
+
+    @property
+    def end_time(self) -> int:
+        """Returns the time at which the operation is scheduled to end."""
+        return self.start_time + self.operation.duration
+
+    def __repr__(self) -> str:
+        return (
+            f"S-Op(operation={self.operation}, "
+            f"start_time={self.start_time}, machine_id={self.machine_id})"
+        )
+
+    def __eq__(self, value: object) -> bool:
+        if not isinstance(value, ScheduledOperation):
+            return False
+        return (
+            self.operation is value.operation
+            and self.start_time == value.start_time
+            and self.machine_id == value.machine_id
+        )

job_shop_lib/visualization/__init__.py

@@ -0,0 +1,25 @@
+"""Package for visualization."""
+
+from job_shop_lib.visualization.gantt_chart import plot_gantt_chart
+from job_shop_lib.visualization.create_gif import (
+    create_gif,
+    create_gantt_chart_frames,
+    plot_gantt_chart_wrapper,
+    create_gif_from_frames,
+)
+from job_shop_lib.visualization.disjunctive_graph import plot_disjunctive_graph
+from job_shop_lib.visualization.agent_task_graph import (
+    plot_agent_task_graph,
+    three_columns_layout,
+)
+
+__all__ = [
+    "plot_gantt_chart",
+    "create_gif",
+    "create_gantt_chart_frames",
+    "plot_gantt_chart_wrapper",
+    "create_gif_from_frames",
+    "plot_disjunctive_graph",
+    "plot_agent_task_graph",
+    "three_columns_layout",
+]

job_shop_lib/visualization/agent_task_graph.py

@@ -0,0 +1,257 @@
+"""Contains functions to plot the agent-task graph of 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.
+
+See: job_shop_lib.graphs.build_agent_task_graph module for more information.
+"""
+
+from typing import Optional
+
+import matplotlib.pyplot as plt
+import networkx as nx
+
+from job_shop_lib.graphs import NodeType, JobShopGraph, Node
+
+
+def plot_agent_task_graph(
+    job_shop_graph: JobShopGraph,
+    title: Optional[str] = None,
+    figsize: tuple[int, int] = (10, 10),
+    layout: Optional[dict[Node, tuple[float, float]]] = None,
+    color_map_name: str = "tab10",
+    node_size: int = 1000,
+    alpha: float = 0.95,
+    add_legend: bool = False,
+) -> plt.Figure:
+    """Returns a plot of the agent-task graph of the instance.
+
+    Machine and job nodes are represented by squares, and the operation nodes
+    are represented by circles.
+
+    Args:
+        job_shop_graph:
+            The job shop graph instance. It should be already initialized with
+            the instance with a valid agent-task graph representation.
+
+    Returns:
+        The figure of the plot. This figure can be used to save the plot to a
+        file or to show it in a Jupyter notebook.
+    """
+    if title is None:
+        title = (
+            f"Agent-Task Graph Visualization: {job_shop_graph.instance.name}"
+        )
+    # Create a new figure and axis
+    fig, ax = plt.subplots(figsize=figsize)
+    fig.suptitle(title)
+
+    # Create the networkx graph
+    graph = job_shop_graph.graph
+
+    # Create the layout if it was not provided
+    if layout is None:
+        layout = three_columns_layout(job_shop_graph)
+
+    # Define colors and shapes
+    color_map = plt.get_cmap(color_map_name)
+    machine_colors = {
+        machine.machine_id: color_map(i)
+        for i, machine in enumerate(
+            job_shop_graph.nodes_by_type[NodeType.MACHINE]
+        )
+    }
+    node_colors = [
+        _get_node_color(node, machine_colors) for node in job_shop_graph.nodes
+    ]
+    node_shapes = {"machine": "s", "job": "d", "operation": "o", "global": "o"}
+
+    # Draw nodes with different shapes based on their type
+    for node_type, shape in node_shapes.items():
+        current_nodes = [
+            node.node_id
+            for node in job_shop_graph.nodes
+            if node.node_type.name.lower() == node_type
+        ]
+        nx.draw_networkx_nodes(
+            graph,
+            layout,
+            nodelist=current_nodes,
+            node_color=[node_colors[i] for i in current_nodes],
+            node_shape=shape,
+            ax=ax,
+            node_size=node_size,
+            alpha=alpha,
+        )
+
+    # Draw edges
+    nx.draw_networkx_edges(graph, layout, ax=ax)
+
+    node_labels = {
+        node.node_id: _get_node_label(node) for node in job_shop_graph.nodes
+    }
+    nx.draw_networkx_labels(graph, layout, node_labels, ax=ax)
+
+    ax.set_axis_off()
+
+    plt.tight_layout()
+
+    # Add to the legend the meaning of m and d
+    if add_legend:
+        plt.figtext(0, 0.95, "d = duration", wrap=True, fontsize=12)
+    return fig
+
+
+def _get_node_color(
+    node: Node, machine_colors: dict[int, tuple[float, float, float, float]]
+) -> tuple[float, float, float, float] | str:
+    if node.node_type == NodeType.OPERATION:
+        return machine_colors[node.operation.machine_id]
+    if node.node_type == NodeType.MACHINE:
+        return machine_colors[node.machine_id]
+
+    return "lightblue"
+
+
+def _get_node_label(node: Node) -> str:
+    if node.node_type == NodeType.OPERATION:
+        return f"d={node.operation.duration}"
+    if node.node_type == NodeType.MACHINE:
+        return f"M{node.machine_id}"
+    if node.node_type == NodeType.JOB:
+        return f"J{node.job_id}"
+    if node.node_type == NodeType.GLOBAL:
+        return "G"
+
+    raise ValueError(f"Invalid node type: {node.node_type}")
+
+
+def three_columns_layout(
+    job_shop_graph: JobShopGraph,
+    *,
+    leftmost_position: float = 0.1,
+    rightmost_position: float = 0.9,
+    topmost_position: float = 1.0,
+    bottommost_position: float = 0.0,
+) -> dict[Node, tuple[float, float]]:
+    """Returns the layout of the agent-task graph.
+
+    The layout is organized in a grid manner. For example, for a JobShopGraph
+    representing a job shop instance with 2 machines and 3 jobs, the layout
+    would be:
+
+    0:  -       O_11      -
+    1:  -       O_12      J1
+    2:  -       O_13      -
+    3:  M1      O_21      -
+    4:  -       O_22      J2
+    5:  -       O_23      -
+    6:  M2      O_31      -
+    7:  -       O_32      J3
+    8:  -       O_33      -
+    9:  -        -        -
+    10: -        G        -
+    Where M1 and M2 are the machine nodes, J1, J2, and J3 are the job
+    nodes, O_ij are the operation nodes, and G is the global node.
+
+    Args:
+        job_shop_graph:
+            The job shop graph instance. It should be already initialized with
+            the instance with a valid agent-task graph representation.
+        leftmost_position:
+            The center position of the leftmost column of the layout. It should
+            be a float between 0 and 1. The default is 0.1.
+        rightmost_position:
+            The center position of the rightmost column of the layout. It
+            should be a float between 0 and 1. The default is 0.9.
+        topmost_position:
+            The center position of the topmost node of the layout. It should be
+            a float between 0 and 1. The default is 0.9.
+        bottommost_position:
+            The center position of the bottommost node of the layout. It should
+            be a float between 0 and 1. The default is 0.1.
+
+    Returns:
+        A dictionary with the position of each node in the graph. The keys are
+        the node ids, and the values are tuples with the x and y coordinates.
+    """
+
+    x_positions = _get_x_positions(leftmost_position, rightmost_position)
+
+    operation_nodes = job_shop_graph.nodes_by_type[NodeType.OPERATION]
+    machine_nodes = job_shop_graph.nodes_by_type[NodeType.MACHINE]
+    job_nodes = job_shop_graph.nodes_by_type[NodeType.JOB]
+    global_nodes = job_shop_graph.nodes_by_type[NodeType.GLOBAL]
+
+    total_positions = len(operation_nodes) + len(global_nodes) * 2
+    y_spacing = (topmost_position - bottommost_position) / total_positions
+
+    layout: dict[Node, tuple[float, float]] = {}
+
+    machines_spacing_multiplier = len(operation_nodes) // len(machine_nodes)
+    layout.update(
+        _assign_positions_from_top(
+            machine_nodes,
+            x_positions["machine"],
+            topmost_position,
+            y_spacing * machines_spacing_multiplier,
+        )
+    )
+    layout.update(
+        (
+            _assign_positions_from_top(
+                operation_nodes,
+                x_positions["operation"],
+                topmost_position,
+                y_spacing,
+            )
+        )
+    )
+
+    if global_nodes:
+        layout[global_nodes[0]] = (
+            x_positions["operation"],
+            bottommost_position,
+        )
+
+    if job_nodes:
+        job_multiplier = len(operation_nodes) // len(job_nodes)
+        layout.update(
+            _assign_positions_from_top(
+                job_nodes,
+                x_positions["job"],
+                topmost_position,
+                y_spacing * job_multiplier,
+            )
+        )
+    return layout
+
+
+def _get_x_positions(
+    leftmost_position: float, rightmost_position: float
+) -> dict[str, float]:
+    center_position = (
+        leftmost_position + (rightmost_position - leftmost_position) / 2
+    )
+    return {
+        "machine": leftmost_position,
+        "operation": center_position,
+        "job": rightmost_position,
+    }
+
+
+def _assign_positions_from_top(
+    nodes: list[Node],
+    x: float,
+    top: float,
+    y_spacing: float,
+) -> dict[Node, tuple[float, float]]:
+    layout: dict[Node, tuple[float, float]] = {}
+    for i, node in enumerate(nodes):
+        y = top - (i + 1) * y_spacing
+        layout[node] = (x, y)
+
+    return layout