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

job_shop_lib/reinforcement_learning/_single_job_shop_graph_env.py

@@ -45,6 +45,7 @@ class SingleJobShopGraphEnv(gym.Env):
 
     Observation Space:
         A dictionary with the following keys:
+
         - "removed_nodes": Binary vector indicating removed graph nodes.
         - "edge_list": Matrix of graph edges in COO format.
         - Feature matrices: Keys corresponding to the composite observer
@@ -54,43 +55,76 @@ class SingleJobShopGraphEnv(gym.Env):
         MultiDiscrete space representing (job_id, machine_id) pairs.
 
     Render Modes:
-        - "human": Displays the current Gantt chart.
-        - "save_video": Saves a video of the complete Gantt chart.
-        - "save_gif": Saves a GIF of the complete Gantt chart.
+
+    - "human": Displays the current Gantt chart.
+    - "save_video": Saves a video of the complete Gantt chart.
+    - "save_gif": Saves a GIF of the complete Gantt chart.
 
     Attributes:
         dispatcher:
             Manages the scheduling process. See
             :class:`~job_shop_lib.dispatching.Dispatcher`.
+
         composite_observer:
             A :class:`~job_shop_lib.dispatching.feature_observers.
             CompositeFeatureObserver` which aggregates features from multiple
             observers.
+
         graph_updater:
             Updates the graph representation after each action. See
             :class:`~job_shop_lib.graphs.GraphUpdater`.
+
         reward_function:
             Computes rewards for actions taken. See
             :class:`~job_shop_lib.reinforcement_learning.RewardObserver`.
+
         action_space:
             Defines the action space. The action is a tuple of two integers
             (job_id, machine_id). The machine_id can be -1 if the selected
             operation can only be scheduled in one machine.
+
         observation_space:
             Defines the observation space. The observation is a dictionary
             with the following keys:
+
             - "removed_nodes": Binary vector indicating removed graph nodes.
             - "edge_list": Matrix of graph edges in COO format.
             - Feature matrices: Keys corresponding to the composite observer
                 features (e.g., "operations", "jobs", "machines").
+
         render_mode:
             The mode for rendering the environment ("human", "save_video",
             "save_gif").
+
         gantt_chart_creator:
             Creates Gantt chart visualizations. See
             :class:`~job_shop_lib.visualization.GanttChartCreator`.
+
         use_padding:
             Whether to use padding in observations. Padding maintains the
+            observation space shape when the number of nodes changes.
+
+    Args:
+        job_shop_graph:
+            The JobShopGraph instance representing the job shop problem.
+        feature_observer_configs:
+            A list of FeatureObserverConfig instances for the feature
+            observers.
+        reward_function_config:
+            The configuration for the reward function.
+        graph_updater_config:
+            The configuration for the graph updater.
+        ready_operations_filter:
+            The function to use for pruning dominated operations.
+        render_mode:
+            The mode for rendering the environment ("human", "save_video",
+            "save_gif").
+        render_config:
+            Configuration for rendering (e.g., paths for saving videos
+            or GIFs). See :class:`~job_shop_lib.visualization.RenderConfig`.
+        use_padding:
+            Whether to use padding in observations. Padding maintains the
+            observation space shape when the number of nodes changes.
     """
 
     metadata = {"render_modes": ["human", "save_video", "save_gif"]}
@@ -116,29 +150,6 @@ class SingleJobShopGraphEnv(gym.Env):
         render_config: RenderConfig | None = None,
         use_padding: bool = True,
     ) -> None:
-        """Initializes the SingleJobShopGraphEnv environment.
-
-        Args:
-            job_shop_graph:
-                The JobShopGraph instance representing the job shop problem.
-            feature_observer_configs:
-                A list of FeatureObserverConfig instances for the feature
-                observers.
-            reward_function_config:
-                The configuration for the reward function.
-            graph_updater_config:
-                The configuration for the graph updater.
-            ready_operations_filter:
-                The function to use for pruning dominated operations.
-            render_mode:
-                The mode for rendering the environment ("human", "save_video",
-                "save_gif").
-            render_config:
-                Configuration for rendering (e.g., paths for saving videos
-                or GIFs).
-            use_padding:
-                Whether to use padding for the edge index.
-        """
         super().__init__()
         # Used for resetting the environment
         self.initial_job_shop_graph = deepcopy(job_shop_graph)
@@ -236,16 +247,16 @@ class SingleJobShopGraphEnv(gym.Env):
 
         Returns:
             A tuple containing the following elements:
+
             - The observation of the environment.
             - The reward obtained.
             - Whether the environment is done.
             - Whether the episode was truncated (always False).
             - A dictionary with additional information. The dictionary
-              contains the following keys:
-                - "feature_names": The names of the features in the
-                  observation.
-                - "available_operations": The operations that are ready to be
-                  scheduled.
+              contains the following keys: "feature_names", the names of the
+              features in the observation; "available_operations", the
+              operations that are ready to be scheduled.
+
         """
         job_id, machine_id = action
         operation = self.dispatcher.next_operation(job_id)

job_shop_lib/reinforcement_learning/_types_and_constants.py

@@ -8,7 +8,7 @@ import numpy as np
 
 from job_shop_lib.dispatching.feature_observers import FeatureType
 from job_shop_lib.visualization import (
-    GanttChartWrapperConfig,
+    PartialGanttChartPlotterConfig,
     GifConfig,
     VideoConfig,
 )
@@ -17,7 +17,7 @@ from job_shop_lib.visualization import (
 class RenderConfig(TypedDict, total=False):
     """Configuration needed to initialize the `GanttChartCreator` class."""
 
-    gantt_chart_wrapper_config: GanttChartWrapperConfig
+    partial_gantt_chart_plotter_config: PartialGanttChartPlotterConfig
     video_config: VideoConfig
     gif_config: GifConfig
 

job_shop_lib/visualization/__init__.py

@@ -1,4 +1,19 @@
-"""Package for visualization."""
+"""Contains functions and classes for visualizing job shop scheduling problems.
+
+.. autosummary::
+
+    plot_gantt_chart
+    get_partial_gantt_chart_plotter
+    PartialGanttChartPlotter
+    create_gantt_chart_video
+    create_gantt_chart_gif
+    plot_disjunctive_graph
+    plot_agent_task_graph
+    GanttChartCreator
+    GifConfig
+    VideoConfig
+
+"""
 
 from job_shop_lib.visualization._plot_gantt_chart import plot_gantt_chart
 from job_shop_lib.visualization._gantt_chart_video_and_gif_creation import (
@@ -8,17 +23,19 @@ from job_shop_lib.visualization._gantt_chart_video_and_gif_creation import (
     get_partial_gantt_chart_plotter,
     create_video_from_frames,
     create_gif_from_frames,
+    PartialGanttChartPlotter,
 )
-from job_shop_lib.visualization._disjunctive_graph import (
+from job_shop_lib.visualization._plot_disjunctive_graph import (
     plot_disjunctive_graph,
+    duration_labeler,
 )
-from job_shop_lib.visualization._agent_task_graph import (
+from job_shop_lib.visualization._plot_agent_task_graph import (
     plot_agent_task_graph,
     three_columns_layout,
 )
 from job_shop_lib.visualization._gantt_chart_creator import (
     GanttChartCreator,
-    GanttChartWrapperConfig,
+    PartialGanttChartPlotterConfig,
     GifConfig,
     VideoConfig,
 )
@@ -35,7 +52,9 @@ __all__ = [
     "plot_agent_task_graph",
     "three_columns_layout",
     "GanttChartCreator",
-    "GanttChartWrapperConfig",
+    "PartialGanttChartPlotterConfig",
     "GifConfig",
     "VideoConfig",
+    "PartialGanttChartPlotter",
+    "duration_labeler",
 ]

job_shop_lib/visualization/_gantt_chart_creator.py

@@ -1,7 +1,6 @@
 """Home of the `GanttChartCreator` class and its configuration types."""
 
 from typing import TypedDict
-
 import matplotlib.pyplot as plt
 
 from job_shop_lib.dispatching import (
@@ -15,57 +14,87 @@ from job_shop_lib.visualization import (
 )
 
 
-class GanttChartWrapperConfig(TypedDict, total=False):
-    """Configuration for creating the plot function with the
-    `plot_gantt_chart_wrapper` function."""
+class PartialGanttChartPlotterConfig(TypedDict, total=False):
+    """A dictionary with the configuration for creating the
+    :class:`PartialGanttChartPlotter` function.
+
+    .. seealso::
+
+        - :class:`PartialGanttChartPlotter`
+        - :func:`get_partial_gantt_chart_plotter`
+    """
 
     title: str | None
+    """The title of the Gantt chart."""
+
     cmap: str
+    """The colormap to use in the Gantt chart."""
+
     show_available_operations: bool
+    """Whether to show available operations in each step."""
 
 
-# We can't use Required here because it's not available in Python 3.10
-class _GifConfigRequired(TypedDict):
-    """Required configuration for creating the GIF."""
+class GifConfig(TypedDict, total=False):
+    """A dictionary with the configuration for creating the GIF using the
+    :func:`create_gantt_chart_gif` function.
 
-    gif_path: str | None
+    .. seealso::
 
+        :func:`create_gantt_chart_gif`
+    """
 
-class _GifConfigOptional(TypedDict, total=False):
-    """Optional configuration for creating the GIF."""
+    gif_path: str | None
+    """The path to save the GIF. It must end with '.gif'."""
 
     fps: int
+    """The frames per second of the GIF. Defaults to 1."""
+
     remove_frames: bool
-    frames_dir: str | None
-    plot_current_time: bool
+    """Whether to remove the frames after creating the GIF."""
 
+    frames_dir: str | None
+    """The directory to store the frames."""
 
-class GifConfig(_GifConfigRequired, _GifConfigOptional):
-    """Configuration for creating the GIF using the `create_gannt_chart_video`
-    function."""
+    plot_current_time: bool
+    """Whether to plot the current time in the Gantt chart."""
 
 
 class VideoConfig(TypedDict, total=False):
     """Configuration for creating the video using the
-    `create_gannt_chart_video` function."""
+    :func:`create_gantt_chart_video` function.
+
+    .. seealso::
+
+        :func:`create_gantt_chart_video`
+    """
 
     video_path: str | None
+    """The path to save the video. It must end with a valid video extension
+    (e.g., '.mp4')."""
+
     fps: int
+    """The frames per second of the video. Defaults to 1."""
+
     remove_frames: bool
+    """Whether to remove the frames after creating the video."""
+
     frames_dir: str | None
+    """The directory to store the frames."""
+
     plot_current_time: bool
+    """Whether to plot the current time in the Gantt chart."""
 
 
 class GanttChartCreator:
     """Facade class that centralizes the creation of Gantt charts, videos
     and GIFs.
 
-    It leverages a `HistoryObserver` to keep track of the operations being
-    scheduled and provides methods to plot the current state
-    of the schedule as a Gantt chart and to create a GIF that shows the
-    evolution of the schedule over time.
+    It leverages a :class:`HistoryObserver` to keep track of the operations
+    being scheduled and provides methods to plot the current state
+    of the schedule as a Gantt chart and to create a GIF or video that shows
+    the evolution of the schedule over time.
 
-    It adds a new `HistoryObserver` to the dispatcher if it does
+    It adds a new :class:`HistoryObserver` to the dispatcher if it does
     not have one already. Otherwise, it uses the observer already present.
 
     Attributes:
@@ -81,72 +110,80 @@ class GanttChartCreator:
             Configuration for creating the video.
         plot_function:
             The function used to plot the Gantt chart when creating the GIF
-            or video. Created using the `plot_gantt_chart_wrapper` function.
+            or video. Created using the :func:`get_partial_gantt_chart_plotter`
+            function.
+
+    Args:
+        dispatcher:
+            The :class:`Dispatcher` class that will be tracked using a
+            :class:`HistoryObserver`.
+        partial_gantt_chart_plotter_config:
+            Configuration for the Gantt chart wrapper function through the
+            :class:`PartialGanttChartPlotterConfig` class. Defaults to
+            ``None``. Valid keys are:
+
+            - title: The title of the Gantt chart.
+            - cmap: The name of the colormap to use.
+            - show_available_operations: Whether to show available
+                operations in each step.
+
+            If ``title`` or ``cmap`` are not provided here and
+            ``infer_gantt_chart_config`` is set to ``True``, the values from
+            ``gantt_chart_config`` will be used if they are present.
+
+            .. seealso::
+
+                - :class:`PartialGanttChartPlotterConfig`
+                - :func:`get_partial_gantt_chart_plotter`
+                - :class:`PartialGanttChartPlotter`
+
+        gif_config:
+            Configuration for creating the GIF. Defaults to ``None``.
+            Valid keys are:
+
+            - gif_path: The path to save the GIF.
+            - fps: The frames per second of the GIF.
+            - remove_frames: Whether to remove the frames after creating
+                the GIF.
+            - frames_dir: The directory to store the frames.
+            - plot_current_time: Whether to plot the current time in the
+                Gantt chart.
+        video_config:
+            Configuration for creating the video. Defaults to ``None``.
+            Valid keys are:
+
+            - video_path: The path to save the video.
+            - fps: The frames per second of the video.
+            - remove_frames: Whether to remove the frames after creating
+                the video.
+            - frames_dir: The directory to store the frames.
+            - plot_current_time: Whether to plot the current time in the
+                Gantt chart.
     """
 
     def __init__(
         self,
         dispatcher: Dispatcher,
-        gantt_chart_wrapper_config: GanttChartWrapperConfig | None = None,
+        partial_gantt_chart_plotter_config: (
+            PartialGanttChartPlotterConfig | None
+        ) = None,
         gif_config: GifConfig | None = None,
         video_config: VideoConfig | None = None,
     ):
-        """Initializes the GanttChartCreator with the given configurations
-        and history observer.
-
-        This class adds a new `HistoryObserver` to the dispatcher if it does
-        not have one already. Otherwise, it uses the observer already present.
-
-        Args:
-            dispatcher:
-                The `Dispatcher` class that will be tracked using a
-                `HistoryObserver`.
-            gantt_chart_wrapper_config:
-                Configuration for the Gantt chart wrapper function. Valid keys
-                are:
-                - title: The title of the Gantt chart.
-                - cmap: The name of the colormap to use.
-                - show_available_operations: Whether to show available
-                    operations in each step.
-
-                If `title` or `cmap` are not provided here and
-                `infer_gantt_chart_config` is set to True, the values from
-                `gantt_chart_config` will be used if they are present.
-            gif_config:
-                Configuration for creating the GIF. Defaults to None.
-                Valid keys are:
-                - gif_path: The path to save the GIF.
-                - fps: The frames per second of the GIF.
-                - remove_frames: Whether to remove the frames after creating
-                    the GIF.
-                - frames_dir: The directory to store the frames.
-                - plot_current_time: Whether to plot the current time in the
-                    Gantt chart.
-            video_config:
-                Configuration for creating the video. Defaults to None.
-                Valid keys are:
-                - video_path: The path to save the video.
-                - fps: The frames per second of the video.
-                - remove_frames: Whether to remove the frames after creating
-                    the video.
-                - frames_dir: The directory to store the frames.
-                - plot_current_time: Whether to plot the current time in the
-                    Gantt chart.
-        """
         if gif_config is None:
-            gif_config = {"gif_path": None}
-        if gantt_chart_wrapper_config is None:
-            gantt_chart_wrapper_config = {}
+            gif_config = {}
+        if partial_gantt_chart_plotter_config is None:
+            partial_gantt_chart_plotter_config = {}
         if video_config is None:
             video_config = {}
 
         self.gif_config = gif_config
-        self.gannt_chart_wrapper_config = gantt_chart_wrapper_config
+        self.gannt_chart_wrapper_config = partial_gantt_chart_plotter_config
         self.video_config = video_config
         self.history_observer: HistoryObserver = (
             dispatcher.create_or_get_observer(HistoryObserver)
         )
-        self.plot_function = get_partial_gantt_chart_plotter(
+        self.partial_gantt_chart_plotter = get_partial_gantt_chart_plotter(
             **self.gannt_chart_wrapper_config
         )
 
@@ -169,37 +206,38 @@ class GanttChartCreator:
         """Plots the current Gantt chart of the schedule.
 
         Returns:
-            tuple[plt.Figure, plt.Axes]:
-                The figure and axes of the plotted Gantt chart.
+            The figure of the plotted Gantt chart.
         """
-        return self.plot_function(
+        a = self.partial_gantt_chart_plotter(
             self.schedule,
             None,
             self.dispatcher.available_operations(),
             self.dispatcher.current_time(),
         )
+        return a
 
     def create_gif(self) -> None:
         """Creates a GIF of the schedule being built using the recorded
         history.
 
         This method uses the history of scheduled operations recorded by the
-        `HistoryTracker` to create a GIF that shows the progression of the
-        scheduling process.
+        :class:`HistoryTracker` to create a GIF that shows the progression of
+        the scheduling process.
 
         The GIF creation process involves:
+
         - Using the history of scheduled operations to generate frames for
             each step of the schedule.
         - Creating a GIF from these frames.
         - Optionally, removing the frames after the GIF is created.
 
         The configuration for the GIF creation can be customized through the
-        `gif_config` attribute.
+        ``gif_config`` attribute.
         """
         create_gantt_chart_gif(
             instance=self.history_observer.dispatcher.instance,
             schedule_history=self.history_observer.history,
-            plot_function=self.plot_function,
+            plot_function=self.partial_gantt_chart_plotter,
             **self.gif_config
         )
 
@@ -208,12 +246,12 @@ class GanttChartCreator:
         history.
 
         This method uses the history of scheduled operations recorded by the
-        `HistoryTracker` to create a video that shows the progression of the
-        scheduling process.
+        :class:`HistoryTracker` to create a video that shows the progression
+        of the scheduling process.
         """
         create_gantt_chart_video(
             instance=self.history_observer.dispatcher.instance,
             schedule_history=self.history_observer.history,
-            plot_function=self.plot_function,
+            plot_function=self.partial_gantt_chart_plotter,
             **self.video_config
         )

job_shop_lib/visualization/_gantt_chart_video_and_gif_creation.py

@@ -38,16 +38,6 @@ class PartialGanttChartPlotter(Protocol):
 
     This kind of functions are created using the
     :func:`plot_gantt_chart_wrapper` function.
-
-    The function should take the following arguments:
-
-    - schedule: The schedule to plot.
-    - makespan: The makespan of the schedule if known. Can be used to fix the
-      x-axis limits.
-    - available_operations: A list of available operations. If ``None``,
-      the available operations are not shown.
-    - current_time: The current time in the schedule. If provided, a red
-      vertical line is plotted at this time.
     """
 
     def __call__(
@@ -57,7 +47,21 @@ class PartialGanttChartPlotter(Protocol):
         available_operations: list[Operation] | None = None,
         current_time: int | None = None,
     ) -> Figure:
-        pass
+        """Plots a Gantt chart for an unfinished schedule.
+
+        Args:
+            schedule:
+                The schedule to plot.
+            makespan:
+                The makespan of the schedule if known. Can be used to fix
+                the x-axis limits.
+            available_operations:
+                A list of available operations. If ``None``,
+                the available operations are not shown.
+            current_time:
+                The current time in the schedule. If provided, a red
+                vertical line is plotted at this time.
+        """
 
 
 def get_partial_gantt_chart_plotter(