job_shop_lib.visualization¶

Contains functions and classes for visualizing job shop scheduling problems.

`plot_gantt_chart`(schedule[, title, ...])	Plots a Gantt chart for the schedule.
`get_partial_gantt_chart_plotter`([title, ...])	Returns a function that plots a Gantt chart for an unfinished schedule.
`PartialGanttChartPlotter`(args, *kwargs)	A protocol for a function that plots an uncompleted Gantt chart for a schedule.
`create_gantt_chart_video`(instance[, ...])	Creates a video of the schedule being built.
`create_gantt_chart_gif`(instance[, gif_path, ...])	Creates a GIF of the schedule being built.
`plot_disjunctive_graph`(job_shop, *[, title, ...])	Plots the disjunctive graph of the given job shop instance or graph.
`plot_agent_task_graph`(job_shop_graph[, ...])	Returns a plot of the agent-task graph of the instance.
`GanttChartCreator`(dispatcher[, ...])	Facade class that centralizes the creation of Gantt charts, videos and GIFs.
`GifConfig`	A dictionary with the configuration for creating the GIF using the `create_gantt_chart_gif()` function.
`VideoConfig`	Configuration for creating the video using the `create_gantt_chart_video()` function.

plot_gantt_chart(schedule, title=None, cmap_name='viridis', xlim=None, number_of_x_ticks=15, job_labels=None, machine_labels=None, legend_title='', x_label='Time units', y_label='Machines')[source]¶

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.

Parameters:

schedule (Schedule) -- The schedule to plot.
title (str | None) -- The title of the plot. If not provided, the title: f"Gantt Chart for {schedule.instance.name} instance" is used. To remove the title, provide an empty string.
cmap_name (str) -- The name of the colormap to use. Default is "viridis".
xlim (int | None) -- The maximum value for the x-axis. If not provided, the makespan of the schedule is used.
number_of_x_ticks (int) -- The number of ticks to use in the x-axis.
job_labels (None | list[str]) -- A list of labels for each job. If None, the labels are automatically generated as "Job 0", "Job 1", etc.
machine_labels (None | list[str]) -- A list of labels for each machine. If None, the labels are automatically generated as "0", "1", etc.
legend_title (str) -- The title of the legend. If not provided, the legend will not have a title.
x_label (str) -- The label for the x-axis. Default is "Time units". To remove the label, provide an empty string.
y_label (str) -- 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.

Return type:

tuple[Figure, Axes]

create_gantt_chart_video(instance, video_path=None, solver=None, plot_function=None, fps=1, remove_frames=True, frames_dir=None, plot_current_time=True, schedule_history=None)[source]¶

Creates a video of the schedule being built.

Parameters:

instance (JobShopInstance) -- The instance of the job shop problem to be scheduled.
video_path (str | None) -- The path to save the video file.
solver (DispatchingRuleSolver | None) -- The dispatching rule solver to use. If not provided, the history of scheduled operations should be provided.
plot_function (PartialGanttChartPlotter | None) -- A function that plots a Gantt chart for a schedule. It should take a Schedule object and the makespan of the schedule as input and return a Figure object. If not provided, a default function is used.
fps (int) -- The number of frames per second in the video.
remove_frames (bool) -- Whether to remove the frames after creating the video.
frames_dir (str | None) -- The directory to save the frames in. If not provided, name_without_the_extension + "_frames" is used.
plot_current_time (bool) -- Whether to plot a vertical line at the current time.
schedule_history (Sequence[ScheduledOperation] | None) -- A sequence of scheduled operations. If not provided, the solver will be used to generate the history.

Return type:

None

create_gantt_chart_gif(instance, gif_path=None, solver=None, plot_function=None, fps=1, remove_frames=True, frames_dir=None, plot_current_time=True, schedule_history=None)[source]¶

Creates a GIF of the schedule being built.

Parameters:

instance (JobShopInstance) -- The instance of the job shop problem to be scheduled.
gif_path (str | None) -- The path to save the GIF file. It should end with ".gif". If not provided, the name of the instance is used.
solver (DispatchingRuleSolver | None) -- The dispatching rule solver to use. If not provided, the history of scheduled operations should be provided.
plot_function (PartialGanttChartPlotter | None) -- A PlotFunction that plots a Gantt chart for a schedule. It should take a Schedule object and the makespan of the schedule as input and return a Figure object. If not provided, a default function is used.
fps (int) -- The number of frames per second in the GIF.
remove_frames (bool) -- Whether to remove the frames after creating the GIF.
frames_dir (str | None) -- The directory to save the frames in. If not provided, gif_path.replace(".gif", "") + "_frames" is used.
plot_current_time (bool) -- Whether to plot a vertical line at the current time.
schedule_history (Sequence[ScheduledOperation] | None) -- A sequence of scheduled operations. If not provided, the solver will be used to generate the history.

Return type:

None

create_gantt_chart_frames(frames_dir, instance, solver, plot_function, plot_current_time=True, schedule_history=None)[source]¶

Creates frames of the Gantt chart for the schedule being built.

Parameters:

frames_dir (str) -- The directory to save the frames in.
instance (JobShopInstance) -- The instance of the job shop problem to be scheduled.
solver (DispatchingRuleSolver | None) -- The dispatching rule solver to use. If not provided, the history of scheduled operations should be provided.
plot_function (PartialGanttChartPlotter) -- A function that plots a Gantt chart for a schedule. It should take a Schedule object and the makespan of the schedule as input and return a Figure object.
plot_current_time (bool) -- Whether to plot a vertical line at the current time.
scheduled_history -- A sequence of scheduled operations. If not provided, the solver
schedule_history (Sequence[ScheduledOperation] | None)

Return type:

None

get_partial_gantt_chart_plotter(title=None, cmap='viridis', show_available_operations=False)[source]¶

Returns a function that plots a Gantt chart for an unfinished schedule.

Parameters:

title (str | None) -- The title of the Gantt chart.
cmap (str) -- The name of the colormap to use.
show_available_operations (bool) -- Whether to show the available operations in the Gantt chart.

Returns:

A function that plots a Gantt chart for a schedule. The function takes the following arguments:

schedule: The schedule to plot.
makespan: The makespan of the schedule.
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.

Return type:

PartialGanttChartPlotter

create_gif_from_frames(frames_dir, gif_path, fps, loop=0)[source]¶

Creates a GIF or video from the frames in the given directory.

Parameters:

frames_dir (str) -- The directory containing the frames to be used in the GIF.
gif_path (str) -- The path to save the GIF file. It should end with ".gif".
fps (int) -- The number of frames per second in the GIF.
loop (int) -- The number of times the GIF should loop. Default is 0, which means the GIF will loop indefinitely. If set to 1, the GIF will loop once. Added in version 0.6.0.

Return type:

None

create_video_from_frames(frames_dir, gif_path, fps, macro_block_size=16)[source]¶

Creates a GIF or video from the frames in the given directory.

Parameters:

frames_dir (str) -- The directory containing the frames to be used in the video.
gif_path (str) -- The path to save the video.
fps (int) -- The number of frames per second.
macro_block_size (int)

Return type:

None

plot_disjunctive_graph(job_shop, *, title=None, figsize=(6, 4), node_size=1600, edge_width=2, font_size=10, arrow_size=35, alpha=0.95, operation_node_labeler=<function duration_labeler>, node_font_color='white', color_map='Dark2_r', disjunctive_edge_color='red', conjunctive_edge_color='black', layout=None, draw_disjunctive_edges=True, conjunctive_edges_additional_params=None, disjunctive_edges_additional_params=None, conjunctive_patch_label='Conjunctive edges', disjunctive_patch_label='Disjunctive edges', legend_text='$p_{ij}=$duration of $O_{ij}$', show_machine_colors_in_legend=True, machine_labels=None, legend_location='upper left', legend_bbox_to_anchor=(1.01, 1), start_node_label='$S$', end_node_label='$T$', font_family='sans-serif')[source]¶

Plots the disjunctive graph of the given job shop instance or graph.

Parameters:

job_shop (JobShopGraph | JobShopInstance) -- The job shop instance or graph to plot. Can be either a JobShopGraph or a JobShopInstance. If a job shop instance is given, the disjunctive graph is built before plotting using the build_disjunctive_graph().
title (str | None) -- The title of the graph (default is "Disjunctive Graph Visualization: {job_shop.instance.name}").
figsize (tuple[float, float]) -- The size of the figure (default is (6, 4)).
node_size (int) -- The size of the nodes (default is 1600).
edge_width (int) -- The width of the edges (default is 2).
font_size (int) -- The font size of the node labels (default is 10).
arrow_size (int) -- The size of the arrows (default is 35).
alpha (float) -- The transparency level of the nodes and edges (default is 0.95).
operation_node_labeler (Callable[[Node], str]) -- A function that formats labels for operation nodes. Receives a Node and returns a string. The default is duration_labeler(), which labels the nodes with their duration.
node_font_color (str) -- The color of the node labels (default is "white").
color_map (str) -- The color map to use for the nodes (default is "Dark2_r").
disjunctive_edge_color (str) -- The color of the disjunctive edges (default is "red").
conjunctive_edge_color (str) -- The color of the conjunctive edges (default is "black").
layout (Callable[[Graph], dict[str, tuple[float, float]]] | None) -- 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.
draw_disjunctive_edges (bool | str) -- 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 and nx.draw_networkx_edges for more information.
conjunctive_edges_additional_params (dict[str, Any] | None) --
Additional parameters to pass to the conjunctive edges when drawing them (default is None). See the documentation of nx.draw_networkx_edges 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 (dict[str, Any] | None) -- Same as conjunctive_edges_additional_params, but for disjunctive edges (default is None).
conjunctive_patch_label (str) -- The label for the conjunctive edges in the legend (default is "Conjunctive edges").
disjunctive_patch_label (str) -- The label for the disjunctive edges in the legend (default is "Disjunctive edges").
legend_text (str) -- 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 (bool) -- Whether to show the colors of the machines in the legend (default is True).
machine_labels (Sequence[str] | None) -- 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 (str) -- The location of the legend (default is "upper left").
legend_bbox_to_anchor (tuple[float, float]) -- The anchor of the legend box (default is (1.01, 1)).
start_node_label (str) -- The label for the start node (default is "$S$").
end_node_label (str) -- The label for the end node (default is "$T$").
font_family (str) -- The font family of the node labels (default is "sans-serif").

Returns:

A matplotlib Figure object representing the disjunctive graph.

Return type:

tuple[Figure, Axes]

Example

job_shop_instance = JobShopInstance(...)  # or a JobShopGraph
fig = plot_disjunctive_graph(job_shop_instance)

plot_agent_task_graph(job_shop_graph, title=None, figsize=(10, 10), layout=None, color_map_name='tab10', node_size=1000, alpha=0.95, add_legend=False)[source]¶

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.

Parameters:

job_shop_graph (JobShopGraph) -- The job shop graph instance. It should be already initialized with the instance with a valid agent-task graph representation.
title (str | None)
figsize (tuple[int, int])
layout (dict[Node, tuple[float, float]] | None)
color_map_name (str)
node_size (int)
alpha (float)
add_legend (bool)

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.

Return type:

Figure

three_columns_layout(job_shop_graph, *, leftmost_position=0.1, rightmost_position=0.9, topmost_position=1.0, bottommost_position=0.0)[source]¶

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.

Parameters:

job_shop_graph (JobShopGraph) -- The job shop graph instance. It should be already initialized with the instance with a valid agent-task graph representation.
leftmost_position (float) -- 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 (float) -- 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 (float) -- 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 (float) -- 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.

Return type:

dict[Node, tuple[float, float]]

class GanttChartCreator(dispatcher, partial_gantt_chart_plotter_config=None, gif_config=None, video_config=None)[source]¶

Bases: object

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 or video that shows the evolution of the schedule over time.

It adds a new HistoryObserver to the dispatcher if it does not have one already. Otherwise, it uses the observer already present.

history_observer¶: The history observer observing the dispatcher's state.

gantt_chart_config¶: Configuration for plotting the Gantt chart.

gif_config¶: Configuration for creating the GIF.

gantt_chart_wrapper_config¶: Configuration for the Gantt chart wrapper function.

video_config¶: Configuration for creating the video.

plot_function¶: The function used to plot the Gantt chart when creating the GIF or video. Created using the get_partial_gantt_chart_plotter() function.

Parameters:

dispatcher (Dispatcher) -- The Dispatcher class that will be tracked using a HistoryObserver.
partial_gantt_chart_plotter_config (PartialGanttChartPlotterConfig | None) --
Configuration for the Gantt chart wrapper function through the 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.
See also
gif_config (GifConfig | None) --
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 (VideoConfig | None) --
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.

property instance¶: The instance being scheduled.

property schedule¶: The current schedule.

property dispatcher¶: The dispatcher being observed.

plot_gantt_chart()[source]¶

Plots the current Gantt chart of the schedule.

Returns:: The figure of the plotted Gantt chart.
Return type:: Figure

create_gif()[source]¶

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.

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.

Return type:: None

create_video()[source]¶

Creates a video of the schedule being built using the recorded 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.

Return type:: None

class PartialGanttChartPlotterConfig[source]¶

Bases: TypedDict

A dictionary with the configuration for creating the PartialGanttChartPlotter function.