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

job_shop_lib/visualization/_plot_disjunctive_graph.py

@@ -0,0 +1,382 @@
+"""Module for visualizing the disjunctive graph of a job shop instance."""
+
+import functools
+from typing import Any
+from collections.abc import Callable, Sequence, Iterable
+import warnings
+import copy
+
+import matplotlib
+import matplotlib.pyplot as plt
+import networkx as nx
+from networkx.drawing.nx_agraph import graphviz_layout
+
+from job_shop_lib import JobShopInstance
+from job_shop_lib.graphs import (
+    JobShopGraph,
+    EdgeType,
+    NodeType,
+    Node,
+    build_disjunctive_graph,
+)
+from job_shop_lib.exceptions import ValidationError
+
+
+Layout = Callable[[nx.Graph], dict[str, tuple[float, float]]]
+
+
+def duration_labeler(node: Node) -> str:
+    """Returns a label for the node with the processing time.
+
+    In the form ``"$p_{ij}=duration$"``, where $i$ is the job id and $j$ is
+    the position in the job.
+
+    Args:
+        node:
+            The operation node to label. See
+            :class:`~job_shop_lib.graphs.Node`.
+    """
+    return (
+        f"$p_{{{node.operation.job_id + 1}"
+        f"{node.operation.position_in_job + 1}}}={node.operation.duration}$"
+    )
+
+
+# This function could be improved by a function extraction refactoring
+# (see `plot_gantt_chart`
+# function as a reference in how to do it). That would solve the
+# "too many locals" warning. However, this refactoring is not a priority at
+# the moment. To compensate, sections are separated by comments.
+# For the "too many arguments" warning no satisfactory solution was
+# found. I believe is still better than using `**kwargs` and losing the
+# function signature or adding a dataclass for configuration (it would add
+# unnecessary complexity). A TypedDict could be used too, but the default
+# values would not be explicit.
+# pylint: disable=too-many-arguments, too-many-locals, too-many-statements
+# pylint: disable=too-many-branches, line-too-long
+def plot_disjunctive_graph(
+    job_shop: JobShopGraph | JobShopInstance,
+    *,
+    title: str | None = None,
+    figsize: tuple[float, float] = (6, 4),
+    node_size: int = 1600,
+    edge_width: int = 2,
+    font_size: int = 10,
+    arrow_size: int = 35,
+    alpha: float = 0.95,
+    operation_node_labeler: Callable[[Node], str] = duration_labeler,
+    node_font_color: str = "white",
+    color_map: str = "Dark2_r",
+    disjunctive_edge_color: str = "red",
+    conjunctive_edge_color: str = "black",
+    layout: Layout | None = None,
+    draw_disjunctive_edges: bool | str = True,
+    conjunctive_edges_additional_params: dict[str, Any] | None = None,
+    disjunctive_edges_additional_params: dict[str, Any] | None = None,
+    conjunctive_patch_label: str = "Conjunctive edges",
+    disjunctive_patch_label: str = "Disjunctive edges",
+    legend_text: str = "$p_{ij}=$duration of $O_{ij}$",
+    show_machine_colors_in_legend: bool = True,
+    machine_labels: Sequence[str] | None = None,
+    legend_location: str = "upper left",
+    legend_bbox_to_anchor: tuple[float, float] = (1.01, 1),
+    start_node_label: str = "$S$",
+    end_node_label: str = "$T$",
+    font_family: str = "sans-serif",
+) -> tuple[plt.Figure, plt.Axes]:
+    r"""Plots the disjunctive graph of the given job shop instance or graph.
+
+    Args:
+        job_shop:
+            The job shop instance or graph to plot. Can be either a
+            :class:`JobShopGraph` or a :class:`JobShopInstance`. If a job shop
+            instance is given, the disjunctive graph is built before plotting
+            using the :func:`~job_shop_lib.graphs.build_disjunctive_graph`.
+        title:
+            The title of the graph (default is ``"Disjunctive Graph
+            Visualization: {job_shop.instance.name}"``).
+        figsize:
+            The size of the figure (default is (6, 4)).
+        node_size:
+            The size of the nodes (default is 1600).
+        edge_width:
+            The width of the edges (default is 2).
+        font_size:
+            The font size of the node labels (default is 10).
+        arrow_size:
+            The size of the arrows (default is 35).
+        alpha:
+            The transparency level of the nodes and edges (default is 0.95).
+        operation_node_labeler:
+            A function that formats labels for operation nodes. Receives a
+            :class:`~job_shop_lib.graphs.Node` and returns a string.
+            The default is :func:`duration_labeler`, which labels the nodes
+            with their duration.
+        node_font_color:
+            The color of the node labels (default is ``"white"``).
+        color_map:
+            The color map to use for the nodes (default is ``"Dark2_r"``).
+        disjunctive_edge_color:
+            The color of the disjunctive edges (default is ``"red"``).
+        conjunctive_edge_color:
+            The color of the conjunctive edges (default is ``"black"``).
+        layout:
+            The layout of the graph (default is ``graphviz_layout`` with
+            ``prog="dot"`` and ``args="-Grankdir=LR"``). If not available,
+            the spring layout is used. To install pygraphviz, check
+            `pygraphviz documentation
+            <https://pygraphviz.github.io/documentation/stable/install.html>`_.
+        draw_disjunctive_edges:
+            Whether to draw disjunctive edges (default is ``True``). If
+            ``False``, only conjunctive edges are drawn. If ``"single_edge",``
+            the disjunctive edges are drawn as undirected edges by removing one
+            of the directions. If using this last option is recommended to set
+            the "arrowstyle" parameter to ``"-"`` or ``"<->"`` in the
+            ``disjunctive_edges_additional_params`` to make the edges look
+            better. See `matplotlib documentation on arrow styles <https://matplotlib.org/stable/api/_as_gen/matplotlib.patches.ArrowStyle.html#matplotlib.patches.ArrowStyle>`_
+            and `nx.draw_networkx_edges <https://networkx.org/documentation/stable/reference/generated/networkx.drawing.nx_pylab.draw_networkx_edges.html>`_
+            for more information.
+        conjunctive_edges_additional_params:
+            Additional parameters to pass to the conjunctive edges when
+            drawing them (default is ``None``). See the documentation of
+            `nx.draw_networkx_edges <https://networkx.org/documentation/stable/reference/generated/networkx.drawing.nx_pylab.draw_networkx_edges.html>`_
+            for more information. The parameters that are explicitly set by
+            this function and should not be part of this dictionary are
+            ``edgelist``, ``pos``, ``width``, ``edge_color``, and
+            ``arrowsize``.
+        disjunctive_edges_additional_params:
+            Same as ``conjunctive_edges_additional_params``, but for
+            disjunctive edges (default is ``None``).
+        conjunctive_patch_label:
+            The label for the conjunctive edges in the legend (default is
+            ``"Conjunctive edges"``).
+        disjunctive_patch_label:
+            The label for the disjunctive edges in the legend (default is
+            ``"Disjunctive edges"``).
+        legend_text:
+            Text to display in the legend after the conjunctive and
+            disjunctive edges labels (default is
+            ``"$p_{ij}=$duration of $O_{ij}$"``).
+        show_machine_colors_in_legend:
+            Whether to show the colors of the machines in the legend
+            (default is ``True``).
+        machine_labels:
+            The labels for the machines (default is
+            ``[f"Machine {i}" for i in range(num_machines)]``). Not used if
+            ``show_machine_colors_in_legend`` is ``False``.
+        legend_location:
+            The location of the legend (default is "upper left").
+        legend_bbox_to_anchor:
+            The anchor of the legend box (default is ``(1.01, 1)``).
+        start_node_label:
+            The label for the start node (default is ``"$S$"``).
+        end_node_label:
+            The label for the end node (default is ``"$T$"``).
+        font_family:
+            The font family of the node labels (default is ``"sans-serif"``).
+
+    Returns:
+        A matplotlib Figure object representing the disjunctive graph.
+
+    Example:
+
+        .. code-block:: python
+
+            job_shop_instance = JobShopInstance(...)  # or a JobShopGraph
+            fig = plot_disjunctive_graph(job_shop_instance)
+
+    """  # noqa: E501
+
+    if isinstance(job_shop, JobShopInstance):
+        job_shop_graph = build_disjunctive_graph(job_shop)
+    else:
+        job_shop_graph = job_shop
+
+    # Set up the plot
+    # ----------------
+    plt.figure(figsize=figsize)
+    if title is None:
+        title = (
+            f"Disjunctive Graph Visualization: {job_shop_graph.instance.name}"
+        )
+    plt.title(title)
+
+    # Set up the layout
+    # -----------------
+    if layout is None:
+        layout = functools.partial(
+            graphviz_layout, prog="dot", args="-Grankdir=LR"
+        )
+
+    temp_graph = copy.deepcopy(job_shop_graph.graph)
+    # Remove disjunctive edges to get a better layout
+    temp_graph.remove_edges_from(
+        [
+            (u, v)
+            for u, v, d in job_shop_graph.graph.edges(data=True)
+            if d["type"] == EdgeType.DISJUNCTIVE
+        ]
+    )
+
+    try:
+        pos = layout(temp_graph)
+    except ImportError:
+        warnings.warn(
+            "Default layout requires pygraphviz http://pygraphviz.github.io/. "
+            "Using spring layout instead.",
+        )
+        pos = nx.spring_layout(temp_graph)
+
+    # Draw nodes
+    # ----------
+    node_colors = [
+        _get_node_color(node)
+        for node in job_shop_graph.nodes
+        if not job_shop_graph.is_removed(node.node_id)
+    ]
+    cmap_func = matplotlib.colormaps.get_cmap(color_map)
+    nx.draw_networkx_nodes(
+        job_shop_graph.graph,
+        pos,
+        node_size=node_size,
+        node_color=node_colors,
+        alpha=alpha,
+        cmap=cmap_func,
+    )
+
+    # Draw edges
+    # ----------
+    conjunctive_edges = [
+        (u, v)
+        for u, v, d in job_shop_graph.graph.edges(data=True)
+        if d["type"] == EdgeType.CONJUNCTIVE
+    ]
+    disjunctive_edges: Iterable[tuple[int, int]] = [
+        (u, v)
+        for u, v, d in job_shop_graph.graph.edges(data=True)
+        if d["type"] == EdgeType.DISJUNCTIVE
+    ]
+    if conjunctive_edges_additional_params is None:
+        conjunctive_edges_additional_params = {}
+    if disjunctive_edges_additional_params is None:
+        disjunctive_edges_additional_params = {}
+
+    nx.draw_networkx_edges(
+        job_shop_graph.graph,
+        pos,
+        edgelist=conjunctive_edges,
+        width=edge_width,
+        edge_color=conjunctive_edge_color,
+        arrowsize=arrow_size,
+        **conjunctive_edges_additional_params,
+    )
+
+    if draw_disjunctive_edges:
+        if draw_disjunctive_edges == "single_edge":
+            # Filter the disjunctive edges to remove one of the directions
+            disjunctive_edges_filtered = set()
+            for u, v in disjunctive_edges:
+                if u > v:
+                    u, v = v, u
+                disjunctive_edges_filtered.add((u, v))
+            disjunctive_edges = disjunctive_edges_filtered
+        nx.draw_networkx_edges(
+            job_shop_graph.graph,
+            pos,
+            edgelist=disjunctive_edges,
+            width=edge_width,
+            edge_color=disjunctive_edge_color,
+            arrowsize=arrow_size,
+            **disjunctive_edges_additional_params,
+        )
+
+    # Draw node labels
+    # ----------------
+    operation_nodes = job_shop_graph.nodes_by_type[NodeType.OPERATION]
+    labels = {}
+    source_node = job_shop_graph.nodes_by_type[NodeType.SOURCE][0]
+    labels[source_node] = start_node_label
+
+    sink_node = job_shop_graph.nodes_by_type[NodeType.SINK][0]
+    labels[sink_node] = end_node_label
+    machine_colors: dict[int, tuple[float, float, float, float]] = {}
+    for operation_node in operation_nodes:
+        if job_shop_graph.is_removed(operation_node.node_id):
+            continue
+        labels[operation_node] = operation_node_labeler(operation_node)
+        machine_id = operation_node.operation.machine_id
+        if machine_id not in machine_colors:
+            machine_colors[machine_id] = cmap_func(
+                (_get_node_color(operation_node) + 1)
+                / job_shop_graph.instance.num_machines
+            )
+
+    nx.draw_networkx_labels(
+        job_shop_graph.graph,
+        pos,
+        labels=labels,
+        font_color=node_font_color,
+        font_size=font_size,
+        font_family=font_family,
+    )
+    # Final touches
+    # -------------
+    plt.axis("off")
+    plt.tight_layout()
+    # Create a legend to indicate the meaning of the edge colors
+    conjunctive_patch = matplotlib.patches.Patch(
+        color=conjunctive_edge_color, label=conjunctive_patch_label
+    )
+    disjunctive_patch = matplotlib.patches.Patch(
+        color=disjunctive_edge_color, label=disjunctive_patch_label
+    )
+    handles = [conjunctive_patch, disjunctive_patch]
+
+    # Add machine colors to the legend
+    if show_machine_colors_in_legend:
+        machine_patches = [
+            matplotlib.patches.Patch(
+                color=color,
+                label=(
+                    machine_labels[machine_id]
+                    if machine_labels is not None
+                    else f"Machine {machine_id}"
+                ),
+            )
+            for machine_id, color in machine_colors.items()
+        ]
+        handles.extend(machine_patches)
+
+    # Add to the legend the meaning of m and d
+    if legend_text:
+        extra = matplotlib.patches.Rectangle(
+            (0, 0),
+            1,
+            1,
+            fc="w",
+            fill=False,
+            edgecolor="none",
+            linewidth=0,
+            label=legend_text,
+        )
+        handles.append(extra)
+
+    plt.legend(
+        handles=handles,
+        loc=legend_location,
+        bbox_to_anchor=legend_bbox_to_anchor,
+        borderaxespad=0.0,
+    )
+    return plt.gcf(), plt.gca()
+
+
+def _get_node_color(node: Node) -> int:
+    """Returns the color of the node."""
+    if node.node_type == NodeType.SOURCE:
+        return -1
+    if node.node_type == NodeType.SINK:
+        return -1
+    if node.node_type == NodeType.OPERATION:
+        return node.operation.machine_id
+
+    raise ValidationError("Invalid node type.")

job_shop_lib/visualization/{_gantt_chart.py → _plot_gantt_chart.py}

@@ -20,16 +20,39 @@ def plot_gantt_chart(
     cmap_name: str = "viridis",
     xlim: int | None = None,
     number_of_x_ticks: int = 15,
+    job_labels: None | list[str] = None,
+    machine_labels: None | list[str] = None,
+    legend_title: str = "",
+    x_label: str = "Time units",
+    y_label: str = "Machines",
 ) -> tuple[Figure, plt.Axes]:
     """Plots a Gantt chart for the schedule.
 
+    This function generates a Gantt chart that visualizes the schedule of jobs
+    across multiple machines. Each job is represented with a unique color,
+    and operations are plotted as bars on the corresponding machines over time.
+
+    The Gantt chart helps to understand the flow of jobs on machines and
+    visualize the makespan of the schedule, i.e., the time it takes to
+    complete all jobs.
+
+    The Gantt chart includes:
+
+    - X-axis: Time units, representing the progression of the schedule.
+    - Y-axis: Machines, which are assigned jobs at various time slots.
+    - Legend: A list of jobs, labeled and color-coded for clarity.
+
+    .. note::
+        The last tick on the x-axis always represents the makespan for easy
+        identification of the completion time.
+
     Args:
         schedule:
             The schedule to plot.
         title:
             The title of the plot. If not provided, the title:
-            `f"Gantt Chart for {schedule.instance.name} instance"`
-            is used.
+            ``f"Gantt Chart for {schedule.instance.name} instance"``
+            is used. To remove the title, provide an empty string.
         cmap_name:
             The name of the colormap to use. Default is "viridis".
         xlim:
@@ -37,21 +60,45 @@ def plot_gantt_chart(
             the schedule is used.
         number_of_x_ticks:
             The number of ticks to use in the x-axis.
+        job_labels:
+            A list of labels for each job. If ``None``, the labels are
+            automatically generated as "Job 0", "Job 1", etc.
+        machine_labels:
+            A list of labels for each machine. If ``None``, the labels are
+            automatically generated as "0", "1", etc.
+        legend_title:
+            The title of the legend. If not provided, the legend will not have
+            a title.
+        x_label:
+            The label for the x-axis. Default is "Time units". To remove the
+            label, provide an empty string.
+        y_label:
+            The label for the y-axis. Default is "Machines". To remove the
+            label, provide an empty string.
+
+    Returns:
+        - A ``matplotlib.figure.Figure`` object.
+        - A ``matplotlib.axes.Axes`` object where the Gantt chart is plotted.
     """
-    fig, ax = _initialize_plot(schedule, title)
-    legend_handles = _plot_machine_schedules(schedule, ax, cmap_name)
-    _configure_legend(ax, legend_handles)
-    _configure_axes(schedule, ax, xlim, number_of_x_ticks)
+    fig, ax = _initialize_plot(schedule, title, x_label, y_label)
+    legend_handles = _plot_machine_schedules(
+        schedule, ax, cmap_name, job_labels
+    )
+    _configure_legend(ax, legend_handles, legend_title)
+    _configure_axes(schedule, ax, xlim, number_of_x_ticks, machine_labels)
     return fig, ax
 
 
 def _initialize_plot(
-    schedule: Schedule, title: str | None
+    schedule: Schedule,
+    title: str | None,
+    x_label: str = "Time units",
+    y_label: str = "Machines",
 ) -> tuple[Figure, plt.Axes]:
     """Initializes the plot."""
     fig, ax = plt.subplots()
-    ax.set_xlabel("Time units")
-    ax.set_ylabel("Machines")
+    ax.set_xlabel(x_label)
+    ax.set_ylabel(y_label)
     ax.grid(True, which="both", axis="x", linestyle="--", linewidth=0.5)
     ax.yaxis.grid(False)
     if title is None:
@@ -61,7 +108,10 @@ def _initialize_plot(
 
 
 def _plot_machine_schedules(
-    schedule: Schedule, ax: plt.Axes, cmap_name: str
+    schedule: Schedule,
+    ax: plt.Axes,
+    cmap_name: str,
+    job_labels: list[str] | None,
 ) -> dict[int, Patch]:
     """Plots the schedules for each machine."""
     max_job_id = schedule.instance.num_jobs - 1
@@ -81,12 +131,20 @@ def _plot_machine_schedules(
             )
             if scheduled_op.job_id not in legend_handles:
                 legend_handles[scheduled_op.job_id] = Patch(
-                    facecolor=color, label=f"Job {scheduled_op.job_id}"
+                    facecolor=color,
+                    label=_get_job_label(job_labels, scheduled_op.job_id),
                 )
 
     return legend_handles
 
 
+def _get_job_label(job_labels: list[str] | None, job_id: int) -> str:
+    """Returns the label for the job."""
+    if job_labels is None:
+        return f"Job {job_id}"
+    return job_labels[job_id]
+
+
 def _plot_scheduled_operation(
     ax: plt.Axes,
     scheduled_op: ScheduledOperation,
@@ -103,7 +161,9 @@ def _plot_scheduled_operation(
     )
 
 
-def _configure_legend(ax: plt.Axes, legend_handles: dict[int, Patch]):
+def _configure_legend(
+    ax: plt.Axes, legend_handles: dict[int, Patch], legend_title: str
+):
     """Configures the legend for the plot."""
     sorted_legend_handles = [
         legend_handles[job_id] for job_id in sorted(legend_handles)
@@ -111,7 +171,8 @@ def _configure_legend(ax: plt.Axes, legend_handles: dict[int, Patch]):
     ax.legend(
         handles=sorted_legend_handles,
         loc="upper left",
-        bbox_to_anchor=(1.01, 1),
+        bbox_to_anchor=(1, 1),
+        title=legend_title,
     )
 
 
@@ -120,6 +181,7 @@ def _configure_axes(
     ax: plt.Axes,
     xlim: Optional[int],
     number_of_x_ticks: int,
+    machine_labels: list[str] | None,
 ):
     """Sets the limits and labels for the axes."""
     num_machines = len(schedule.schedule)
@@ -132,7 +194,9 @@ def _configure_axes(
             for i in range(num_machines)
         ]
     )
-    ax.set_yticklabels([str(i) for i in range(num_machines)])
+    if machine_labels is None:
+        machine_labels = [str(i) for i in range(num_machines)]
+    ax.set_yticklabels(machine_labels)
     makespan = schedule.makespan()
     xlim = xlim if xlim is not None else makespan
     ax.set_xlim(0, xlim)

{job_shop_lib-1.0.0a2.dist-info → job_shop_lib-1.0.0a4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: job-shop-lib
-Version: 1.0.0a2
+Version: 1.0.0a4
 Summary: An easy-to-use and modular Python library for the Job Shop Scheduling Problem (JSSP)
 License: MIT
 Author: Pabloo22
@@ -29,6 +29,7 @@ Description-Content-Type: text/markdown
 <h1>JobShopLib</h1>
 
 [![Tests](https://github.com/Pabloo22/job_shop_lib/actions/workflows/tests.yaml/badge.svg)](https://github.com/Pabloo22/job_shop_lib/actions/workflows/tests.yaml)
+[![Documentation Status](https://readthedocs.org/projects/job-shop-lib/badge/?version=latest)](https://job-shop-lib.readthedocs.io/en/latest/?badge=latest)
 ![Python versions](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue)
 [![Black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -39,7 +40,7 @@ JobShopLib is a Python package for creating, solving, and visualizing Job Shop S
 
 It follows a modular design, allowing users to easily extend the library with new solvers, dispatching rules, visualization functions, etc.
 
-See [this](https://colab.research.google.com/drive/1XV_Rvq1F2ns6DFG8uNj66q_rcowwTZ4H?usp=sharing) Google Colab notebook for a quick start guide! 
+See the [documentation](https://job-shop-lib.readthedocs.io/en/latest/) for more details about the latest version.
 
 ## Installation :package:
 
@@ -47,12 +48,23 @@ See [this](https://colab.research.google.com/drive/1XV_Rvq1F2ns6DFG8uNj66q_rcoww
 
 JobShopLib is distributed on [PyPI](https://pypi.org/project/job-shop-lib/) and it supports Python 3.10+.
 
-You can install the latest version using `pip`:
+You can install the latest stable version (version 0.5.1) using `pip`:
 
 ```bash
 pip install job-shop-lib
 ```
 
+See [this](https://colab.research.google.com/drive/1XV_Rvq1F2ns6DFG8uNj66q_rcowwTZ4H?usp=sharing) Google Colab notebook for a quick start guide! 
+
+
+Version 1.0.0 is currently in alpha stage and can be installed with:
+
+```bash
+pip install job-shop-lib==1.0.0a4
+```
+
+Although this version is not stable and may contain breaking changes in subsequent releases, it is recommended to install it to access the new reinforcement learning environments and familiarize yourself with new changes (see the [latest pull requests](https://github.com/Pabloo22/job_shop_lib/pulls?q=is%3Apr+is%3Aclosed)). This version is the first one with a [documentation page](https://job-shop-lib.readthedocs.io/en/latest/).
+
 <!-- end installation -->
 
 <!-- key features -->