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

job_shop_lib/dispatching/rules/_dispatching_rules_functions.py

@@ -21,7 +21,7 @@ from job_shop_lib.dispatching.feature_observers import (
 def shortest_processing_time_rule(dispatcher: Dispatcher) -> Operation:
     """Dispatches the operation with the shortest duration."""
     return min(
-        dispatcher.ready_operations(),
+        dispatcher.available_operations(),
         key=lambda operation: operation.duration,
     )
 
@@ -29,7 +29,7 @@ def shortest_processing_time_rule(dispatcher: Dispatcher) -> Operation:
 def first_come_first_served_rule(dispatcher: Dispatcher) -> Operation:
     """Dispatches the operation with the lowest position in job."""
     return min(
-        dispatcher.ready_operations(),
+        dispatcher.available_operations(),
         key=lambda operation: operation.position_in_job,
     )
 
@@ -41,7 +41,7 @@ def most_work_remaining_rule(dispatcher: Dispatcher) -> Operation:
         job_remaining_work[operation.job_id] += operation.duration
 
     return max(
-        dispatcher.ready_operations(),
+        dispatcher.available_operations(),
         key=lambda operation: job_remaining_work[operation.job_id],
     )
 
@@ -53,14 +53,14 @@ def most_operations_remaining_rule(dispatcher: Dispatcher) -> Operation:
         job_remaining_operations[operation.job_id] += 1
 
     return max(
-        dispatcher.ready_operations(),
+        dispatcher.available_operations(),
         key=lambda operation: job_remaining_operations[operation.job_id],
     )
 
 
 def random_operation_rule(dispatcher: Dispatcher) -> Operation:
     """Dispatches a random operation."""
-    return random.choice(dispatcher.ready_operations())
+    return random.choice(dispatcher.available_operations())
 
 
 def score_based_rule(
@@ -80,7 +80,7 @@ def score_based_rule(
     def rule(dispatcher: Dispatcher) -> Operation:
         scores = score_function(dispatcher)
         return max(
-            dispatcher.ready_operations(),
+            dispatcher.available_operations(),
             key=lambda operation: scores[operation.job_id],
         )
 
@@ -102,7 +102,7 @@ def score_based_rule_with_tie_breaker(
     """
 
     def rule(dispatcher: Dispatcher) -> Operation:
-        candidates = dispatcher.ready_operations()
+        candidates = dispatcher.available_operations()
         for scoring_function in score_functions:
             scores = scoring_function(dispatcher)
             best_score = max(scores)
@@ -126,7 +126,7 @@ def shortest_processing_time_score(dispatcher: Dispatcher) -> list[int]:
     """Scores each job based on the duration of the next operation."""
     num_jobs = dispatcher.instance.num_jobs
     scores = [0] * num_jobs
-    for operation in dispatcher.ready_operations():
+    for operation in dispatcher.available_operations():
         scores[operation.job_id] = -operation.duration
     return scores
 
@@ -135,7 +135,7 @@ def first_come_first_served_score(dispatcher: Dispatcher) -> list[int]:
     """Scores each job based on the position of the next operation."""
     num_jobs = dispatcher.instance.num_jobs
     scores = [0] * num_jobs
-    for operation in dispatcher.ready_operations():
+    for operation in dispatcher.available_operations():
         scores[operation.job_id] = operation.operation_id
     return scores
 

job_shop_lib/graphs/__init__.py

@@ -1,5 +1,7 @@
 """Package for graph related classes and functions.
 
+The main classes and functions available in this package are:
+
 .. autosummary::
     JobShopGraph
     Node

job_shop_lib/graphs/_build_agent_task_graph.py

@@ -13,8 +13,8 @@ job, and the global node is connected to all machine and job nodes.
 
 References:
 - Junyoung Park, Sanjar Bakhtiyar, and Jinkyoo Park. Schedulenet: Learn to
-solve multi-agent scheduling problems with reinforcement learning. ArXiv,
-abs/2106.03051, 2021.
+  solve multi-agent scheduling problems with reinforcement learning. ArXiv,
+  abs/2106.03051, 2021.
 """
 
 import itertools

job_shop_lib/graphs/_constants.py

@@ -11,7 +11,24 @@ class EdgeType(enum.Enum):
 
 
 class NodeType(enum.Enum):
-    """Enumeration of node types."""
+    """Enumeration of node types.
+
+    Nodes of type :class:`NodeType.OPERATION`, :class:`NodeType.MACHINE`, and
+    :class:`NodeType.JOB` have specific attributes associated with them in the
+    :class:`Node` class.
+
+    On the other hand, Nodes of type :class:`NodeType.GLOBAL`,
+    :class:`NodeType.SOURCE`, and :class:`NodeType.SINK` are used to represent
+    different concepts in the graph and accesing them, but they do not have
+    specific attributes associated with them.
+
+    .. tip::
+
+        While uncommon, it can be useful to extend this enumeration with
+        additional node types. This can be achieved using
+        `aenum <https://github.com/ethanfurman/aenum>`_'s
+        ``extend_enum`` (requires using Python 3.11+).
+    """
 
     OPERATION = enum.auto()
     MACHINE = enum.auto()

job_shop_lib/graphs/_job_shop_graph.py

@@ -13,10 +13,10 @@ NODE_ATTR = "node"
 
 # pylint: disable=too-many-instance-attributes
 class JobShopGraph:
-    """Data structure to represent a `JobShopInstance` as a graph.
+    """Represents a :class:`JobShopInstance` as a heterogeneous directed graph.
 
     Provides a comprehensive graph-based representation of a job shop
-    scheduling problem, utilizing the `networkx` library to model the complex
+    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
@@ -25,25 +25,40 @@ class JobShopGraph:
     This transformation allows for the application of graph algorithms
     to analyze and solve scheduling problems.
 
-    Attributes:
+    Args:
         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.
+            The job shop instance that the graph represents.
+        add_operation_nodes:
+            Whether to add nodes of type :class:`NodeType.OPERATION` to the
+            to the graph. If set to ``False``, the graph will be empty, and
+            operation nodes will need to be added manually.
     """
 
-    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.
-        """
+    __slots__ = {
+        "instance": "The job shop instance that the graph represents.",
+        "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": "List of all nodes added to the graph.",
+        "_nodes_by_type": "Dictionary mapping node types to lists of nodes.",
+        "_nodes_by_machine": (
+            "List of lists mapping machine ids to operation nodes."
+        ),
+        "_nodes_by_job": "List of lists mapping job ids to operation nodes.",
+        "_next_node_id": (
+            "The id to assign to the next node added to thegraph."
+        ),
+        "removed_nodes": (
+            "List of boolean values indicating whether a node has been "
+            "removed from the graph."
+        ),
+    }
+
+    def __init__(
+        self, instance: JobShopInstance, add_operation_nodes: bool = True
+    ):
         self.graph = nx.DiGraph()
         self.instance = instance
 
@@ -59,7 +74,8 @@ class JobShopGraph:
         ]
         self._next_node_id = 0
         self.removed_nodes: list[bool] = []
-        self._add_operation_nodes()
+        if add_operation_nodes:
+            self.add_operation_nodes()
 
     @property
     def nodes(self) -> list[Node]:
@@ -103,7 +119,7 @@ class JobShopGraph:
         """Number of job nodes in the graph."""
         return len(self._nodes_by_type[NodeType.JOB])
 
-    def _add_operation_nodes(self) -> None:
+    def add_operation_nodes(self) -> None:
         """Adds operation nodes to the graph."""
         for job in self.instance.jobs:
             for operation in job:

job_shop_lib/graphs/_node.py

@@ -9,7 +9,7 @@ from job_shop_lib.graphs._constants import NodeType
 
 
 class Node:
-    """Data structure to represent a node in the `JobShopGraph`.
+    """Represents a node in the :class:`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
@@ -18,11 +18,15 @@ class Node:
     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`
+    +----------------+---------------------+
+    | 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
@@ -31,25 +35,47 @@ class Node:
     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"
-    ```
+    .. code-block:: python
 
-    Attributes:
+        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
-            ...
+            The type of the node. See :class:`NodeType` for theavailable types.
+        operation:
+            The operation of the node. Required if ``node_type`` is
+            :attr:`NodeType.OPERATION`.
+        machine_id:
+            The id of the machine. Required if ``node_type`` is
+            :attr:`NodeType.MACHINE`.
+        job_id:
+            The id of the job. Required if ``node_type`` is
+            :attr:`NodeType.JOB`.
+
+    Raises:
+        ValidationError:
+            If the ``node_type`` is :attr:`NodeType.OPERATION`,
+            :attr:`NodeType.MACHINE`, or :attr:`NodeType.JOB` and the
+            corresponding ``operation``, ``machine_id``, or ``job_id`` is
+            ``None``, respectively.
+
     """
 
-    __slots__ = "node_type", "_node_id", "_operation", "_machine_id", "_job_id"
+    __slots__ = {
+        "node_type": "The type of the node.",
+        "_node_id": "Unique identifier for the node.",
+        "_operation": (
+            "The operation associated with the node."
+        ),
+        "_machine_id": (
+            "The machine ID associated with the node."
+        ),
+        "_job_id": "The job ID associated with the node.",
+    }
 
     def __init__(
         self,
@@ -58,34 +84,6 @@ class Node:
         machine_id: int | None = None,
         job_id: int | None = None,
     ):
-        """Initializes the node with the given attributes.
-
-        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.
-
-        Raises:
-            ValidationError:
-                If the node_type is OPERATION and operation is None.
-            ValidationError:
-                If the node_type is MACHINE and machine_id is None.
-            ValidationError:
-                If the node_type is JOB and job_id is None.
-        """
         if node_type == NodeType.OPERATION and operation is None:
             raise ValidationError("Operation node must have an operation.")
 
@@ -95,7 +93,7 @@ class Node:
         if node_type == NodeType.JOB and job_id is None:
             raise ValidationError("Job node must have a job_id.")
 
-        self.node_type = node_type
+        self.node_type: NodeType = node_type
         self._node_id: int | None = None
 
         self._operation = operation
@@ -119,7 +117,11 @@ class Node:
     def operation(self) -> Operation:
         """Returns the operation of the node.
 
-        This property is mandatory for nodes of type `OPERATION`.
+        This property is mandatory for nodes of type
+        :class:`NodeType.OPERATION`.
+
+        Raises:
+            UninitializedAttributeError: If the node has no operation.
         """
         if self._operation is None:
             raise UninitializedAttributeError("Node has no operation.")
@@ -130,9 +132,12 @@ class Node:
         """Returns the `machine_id` of the node.
 
         This property is mandatory for nodes of type `MACHINE`.
+
+        Raises:
+            UninitializedAttributeError: If the node has no ``machine_id``.
         """
         if self._machine_id is None:
-            raise UninitializedAttributeError("Node has no `machine_id`.")
+            raise UninitializedAttributeError("Node has no ``machine_id``.")
         return self._machine_id
 
     @property
@@ -140,6 +145,9 @@ class Node:
         """Returns the `job_id` of the node.
 
         This property is mandatory for nodes of type `JOB`.
+
+        Raises:
+            UninitializedAttributeError: If the node has no `job_id`.
         """
         if self._job_id is None:
             raise UninitializedAttributeError("Node has no `job_id`.")

job_shop_lib/graphs/graph_updaters/__init__.py

@@ -1,5 +1,15 @@
 """Contains classes and functions for updating the graph representation of the
-job shop scheduling problem."""
+job shop scheduling problem.
+
+Currently, the following classes and utilities are available:
+
+.. autosummary::
+
+    GraphUpdater
+    ResidualGraphUpdater
+    remove_completed_operations
+
+"""
 
 from ._graph_updater import GraphUpdater
 from ._utils import remove_completed_operations

job_shop_lib/reinforcement_learning/_single_job_shop_graph_env.py

@@ -260,7 +260,7 @@ class SingleJobShopGraphEnv(gym.Env):
         truncated = False
         info: dict[str, Any] = {
             "feature_names": self.composite_observer.column_names,
-            "available_operations": self.dispatcher.ready_operations(),
+            "available_operations": self.dispatcher.available_operations(),
         }
         return obs, reward, done, truncated, info
 

job_shop_lib/visualization/__init__.py

@@ -1,11 +1,11 @@
 """Package for visualization."""
 
-from job_shop_lib.visualization._gantt_chart import plot_gantt_chart
+from job_shop_lib.visualization._plot_gantt_chart import plot_gantt_chart
 from job_shop_lib.visualization._gantt_chart_video_and_gif_creation import (
-    create_gif,
+    create_gantt_chart_gif,
     create_gantt_chart_video,
     create_gantt_chart_frames,
-    plot_gantt_chart_wrapper,
+    get_partial_gantt_chart_plotter,
     create_video_from_frames,
     create_gif_from_frames,
 )
@@ -26,9 +26,9 @@ from job_shop_lib.visualization._gantt_chart_creator import (
 __all__ = [
     "plot_gantt_chart",
     "create_gantt_chart_video",
-    "create_gif",
+    "create_gantt_chart_gif",
     "create_gantt_chart_frames",
-    "plot_gantt_chart_wrapper",
+    "get_partial_gantt_chart_plotter",
     "create_gif_from_frames",
     "create_video_from_frames",
     "plot_disjunctive_graph",

job_shop_lib/visualization/_gantt_chart_creator.py

@@ -10,8 +10,8 @@ from job_shop_lib.dispatching import (
 )
 from job_shop_lib.visualization import (
     create_gantt_chart_video,
-    plot_gantt_chart_wrapper,
-    create_gif,
+    get_partial_gantt_chart_plotter,
+    create_gantt_chart_gif,
 )
 
 
@@ -146,7 +146,7 @@ class GanttChartCreator:
         self.history_observer: HistoryObserver = (
             dispatcher.create_or_get_observer(HistoryObserver)
         )
-        self.plot_function = plot_gantt_chart_wrapper(
+        self.plot_function = get_partial_gantt_chart_plotter(
             **self.gannt_chart_wrapper_config
         )
 
@@ -175,7 +175,7 @@ class GanttChartCreator:
         return self.plot_function(
             self.schedule,
             None,
-            self.dispatcher.ready_operations(),
+            self.dispatcher.available_operations(),
             self.dispatcher.current_time(),
         )
 
@@ -196,7 +196,7 @@ class GanttChartCreator:
         The configuration for the GIF creation can be customized through the
         `gif_config` attribute.
         """
-        create_gif(
+        create_gantt_chart_gif(
             instance=self.history_observer.dispatcher.instance,
             schedule_history=self.history_observer.history,
             plot_function=self.plot_function,