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

job_shop_lib/generation/_general_instance_generator.py

@@ -17,36 +17,58 @@ class GeneralInstanceGenerator(InstanceGenerator):
     durations, and more.
 
     The class supports both single instance generation and iteration over
-    multiple instances, controlled by the `iteration_limit` parameter. It
-    implements the iterator protocol, allowing it to be used in a `for` loop.
+    multiple instances, controlled by the ``iteration_limit`` parameter. It
+    implements the iterator protocol, allowing it to be used in a ``for`` loop.
 
     Note:
         When used as an iterator, the generator will produce instances until it
-        reaches the specified `iteration_limit`. If `iteration_limit` is None,
-        it will continue indefinitely.
+        reaches the specified ``iteration_limit``. If ``iteration_limit`` is
+        ``None``, it will continue indefinitely.
 
     Attributes:
         num_jobs_range:
             The range of the number of jobs to generate. If a single
-            int is provided, it is used as both the minimum and maximum.
+            ``int`` is provided, it is used as both the minimum and maximum.
         duration_range:
             The range of durations for each operation.
         num_machines_range:
             The range of the number of machines available. If a
-            single int is provided, it is used as both the minimum and maximum.
+            single ``int`` is provided, it is used as both the minimum and
+            maximum.
         machines_per_operation:
             Specifies how many machines each operation
-            can be assigned to. If a single int is provided, it is used for
+            can be assigned to. If a single ``int`` is provided, it is used for
             all operations.
         allow_less_jobs_than_machines:
-            If True, allows generating instances where the number of jobs is
-            less than the number of machines.
+            If ``True``, allows generating instances where the number of jobs
+            is less than the number of machines.
         allow_recirculation:
-            If True, a job can visit the same machine more than once.
+            If ``True``, a job can visit the same machine more than once.
         name_suffix:
             A suffix to append to each instance's name for identification.
         seed:
             Seed for the random number generator to ensure reproducibility.
+
+    Args:
+        num_jobs:
+            The range of the number of jobs to generate.
+        num_machines:
+            The range of the number of machines available.
+        duration_range:
+            The range of durations for each operation.
+        allow_less_jobs_than_machines:
+            Allows instances with fewer jobs than machines.
+        allow_recirculation:
+            Allows jobs to visit the same machine multiple times.
+        machines_per_operation:
+            Specifies how many machines each operation can be assigned to.
+            If a single ``int`` is provided, it is used for all operations.
+        name_suffix:
+            Suffix for instance names.
+        seed:
+            Seed for the random number generator.
+        iteration_limit:
+            Maximum number of instances to generate in iteration mode.
     """
 
     def __init__(  # pylint: disable=too-many-arguments
@@ -61,29 +83,6 @@ class GeneralInstanceGenerator(InstanceGenerator):
         seed: int | None = None,
         iteration_limit: int | None = None,
     ):
-        """Initializes the instance generator with the given parameters.
-
-        Args:
-            num_jobs:
-                The range of the number of jobs to generate.
-            num_machines:
-                The range of the number of machines available.
-            duration_range:
-                The range of durations for each operation.
-            allow_less_jobs_than_machines:
-                Allows instances with fewer jobs than machines.
-            allow_recirculation:
-                Allows jobs to visit the same machine multiple times.
-            machines_per_operation:
-                Specifies how many machines each operation can be assigned to.
-                If a single int is provided, it is used for all operations.
-            name_suffix:
-                Suffix for instance names.
-            seed:
-                Seed for the random number generator.
-            iteration_limit:
-                Maximum number of instances to generate in iteration mode.
-        """
         super().__init__(
             num_jobs=num_jobs,
             num_machines=num_machines,
@@ -153,7 +152,7 @@ class GeneralInstanceGenerator(InstanceGenerator):
         Args:
             available_machines:
                 A list of available machine_ids to choose from.
-                If None, all machines are available.
+                If ``None``, all machines are available.
         """
         duration = random.randint(*self.duration_range)
 

job_shop_lib/generation/_instance_generator.py

@@ -32,6 +32,20 @@ class InstanceGenerator(abc.ABC):
             A suffix to append to each instance's name for identification.
         seed:
             Seed for the random number generator to ensure reproducibility.
+
+    Args:
+        num_jobs:
+            The range of the number of jobs to generate.
+        num_machines:
+            The range of the number of machines available.
+        duration_range:
+            The range of durations for each operation.
+        name_suffix:
+            Suffix for instance names.
+        seed:
+            Seed for the random number generator.
+        iteration_limit:
+            Maximum number of instances to generate in iteration mode.
     """
 
     def __init__(  # pylint: disable=too-many-arguments
@@ -43,23 +57,6 @@ class InstanceGenerator(abc.ABC):
         seed: int | None = None,
         iteration_limit: int | None = None,
     ):
-        """Initializes the instance generator with the given parameters.
-
-        Args:
-            num_jobs:
-                The range of the number of jobs to generate.
-            num_machines:
-                The range of the number of machines available.
-            duration_range:
-                The range of durations for each operation.
-            name_suffix:
-                Suffix for instance names.
-            seed:
-                Seed for the random number generator.
-            iteration_limit:
-                Maximum number of instances to generate in iteration mode.
-        """
-
         if isinstance(num_jobs, int):
             num_jobs = (num_jobs, num_jobs)
         if isinstance(num_machines, int):

job_shop_lib/generation/_transformations.py

@@ -111,7 +111,17 @@ class AddDurationNoise(Transformation):
 
 class RemoveJobs(Transformation):
     """Removes jobs randomly until the number of jobs is within a specified
-    range."""
+    range.
+
+    Args:
+        min_jobs:
+            The minimum number of jobs to remain in the instance.
+        max_jobs:
+            The maximum number of jobs to remain in the instance.
+        target_jobs:
+            If specified, the number of jobs to remain in the
+            instance. Overrides ``min_jobs`` and ``max_jobs``.
+    """
 
     def __init__(
         self,
@@ -120,13 +130,6 @@ class RemoveJobs(Transformation):
         target_jobs: int | None = None,
         suffix: str | None = None,
     ):
-        """
-        Args:
-            min_jobs: The minimum number of jobs to remain in the instance.
-            max_jobs: The maximum number of jobs to remain in the instance.
-            target_jobs: If specified, the number of jobs to remain in the
-                instance. Overrides min_jobs and max_jobs.
-        """
         if suffix is None:
             suffix = f"_jobs={min_jobs}-{max_jobs}"
         super().__init__(suffix=suffix)

job_shop_lib/graphs/__init__.py

@@ -7,6 +7,7 @@ The main classes and functions available in this package are:
     Node
     NodeType
     build_disjunctive_graph
+    build_solved_disjunctive_graph
     build_agent_task_graph
     build_complete_agent_task_graph
     build_agent_task_graph_with_jobs
@@ -18,6 +19,7 @@ from job_shop_lib.graphs._node import Node
 from job_shop_lib.graphs._job_shop_graph import JobShopGraph, NODE_ATTR
 from job_shop_lib.graphs._build_disjunctive_graph import (
     build_disjunctive_graph,
+    build_solved_disjunctive_graph,
     add_disjunctive_edges,
     add_conjunctive_edges,
     add_source_sink_nodes,
@@ -62,4 +64,5 @@ __all__ = [
     "add_global_node",
     "add_machine_global_edges",
     "add_job_global_edges",
+    "build_solved_disjunctive_graph",
 ]

job_shop_lib/graphs/_build_disjunctive_graph.py

@@ -18,14 +18,15 @@ each disjunctive edge such that the overall processing time is minimized.
 
 import itertools
 
-from job_shop_lib import JobShopInstance
+from job_shop_lib import JobShopInstance, Schedule
 from job_shop_lib.graphs import JobShopGraph, EdgeType, NodeType, Node
 
 
 def build_disjunctive_graph(instance: JobShopInstance) -> JobShopGraph:
     """Builds and returns a disjunctive graph for the given job shop instance.
 
-    This function creates a complete disjunctive graph from a JobShopInstance.
+    This function creates a complete disjunctive graph from a
+    :JobShopInstance.
     It starts by initializing a JobShopGraph object and proceeds by adding
     disjunctive edges between operations using the same machine, conjunctive
     edges between successive operations in the same job, and finally, special
@@ -40,7 +41,7 @@ def build_disjunctive_graph(instance: JobShopInstance) -> JobShopGraph:
         the graph.
 
     Returns:
-        JobShopGraph: A JobShopGraph object representing the disjunctive graph
+        A :class:`JobShopGraph` object representing the disjunctive graph
         of the job shop scheduling problem.
     """
     graph = JobShopGraph(instance)
@@ -51,6 +52,43 @@ def build_disjunctive_graph(instance: JobShopInstance) -> JobShopGraph:
     return graph
 
 
+def build_solved_disjunctive_graph(schedule: Schedule) -> JobShopGraph:
+    """Builds and returns a disjunctive graph for the given solved schedule.
+
+    This function constructs a disjunctive graph from the given schedule,
+    keeping only the disjunctive edges that represent the chosen ordering
+    of operations on each machine as per the solution schedule.
+
+    Args:
+        schedule (Schedule): The solved schedule that contains the sequencing
+        of operations on each machine.
+
+    Returns:
+        A JobShopGraph object representing the disjunctive graph
+        of the solved job shop scheduling problem.
+    """
+    # Build the base disjunctive graph from the job shop instance
+    graph = JobShopGraph(schedule.instance)
+    add_conjunctive_edges(graph)
+    add_source_sink_nodes(graph)
+    add_source_sink_edges(graph)
+
+    # Iterate over each machine and add only the edges that match the solution
+    # order
+    for machine_schedule in schedule.schedule:
+        for i, scheduled_operation in enumerate(machine_schedule):
+            if i + 1 >= len(machine_schedule):
+                break
+            next_scheduled_operation = machine_schedule[i + 1]
+            graph.add_edge(
+                scheduled_operation.operation.operation_id,
+                next_scheduled_operation.operation.operation_id,
+                type=EdgeType.DISJUNCTIVE,
+            )
+
+    return graph
+
+
 def add_disjunctive_edges(graph: JobShopGraph) -> None:
     """Adds disjunctive edges to the graph."""
 

job_shop_lib/graphs/graph_updaters/_graph_updater.py

@@ -23,6 +23,17 @@ class GraphUpdater(DispatcherObserver):
         job_shop_graph:
             The current job shop graph. This is the graph that is updated
             after each scheduled operation.
+
+    Args:
+        dispatcher:
+            The dispatcher instance to observe.
+        job_shop_graph:
+            The job shop graph to update.
+        subscribe:
+            Whether to subscribe to the dispatcher. If ``True``, the
+            observer will subscribe to the dispatcher when it is
+            initialized. If ``False``, the observer will not subscribe
+            to the dispatcher.
     """
 
     def __init__(
@@ -32,19 +43,6 @@ class GraphUpdater(DispatcherObserver):
         *,
         subscribe: bool = True,
     ):
-        """Initializes the class.
-
-        Args:
-            dispatcher:
-                The dispatcher instance to observe.
-            job_shop_graph:
-                The job shop graph to update.
-            subscribe:
-                Whether to subscribe to the dispatcher. If ``True``, the
-                observer will subscribe to the dispatcher when it is
-                initialized. If ``False``, the observer will not subscribe
-                to the dispatcher.
-        """
         super().__init__(dispatcher, subscribe=subscribe)
         self.initial_job_shop_graph = deepcopy(job_shop_graph)
         self.job_shop_graph = job_shop_graph

job_shop_lib/graphs/graph_updaters/_residual_graph_updater.py

@@ -25,9 +25,24 @@ class ResidualGraphUpdater(GraphUpdater):
 
     Attributes:
         remove_completed_machine_nodes:
-            If True, removes completed machine nodes from the graph.
+            If ``True``, removes completed machine nodes from the graph.
         remove_completed_job_nodes:
-            If True, removes completed job nodes from the graph.
+            If ``True``, removes completed job nodes from the graph.
+
+    Args:
+        dispatcher:
+            The dispatcher instance to observe.
+        job_shop_graph:
+            The job shop graph to update.
+        subscribe:
+            If ``True``, automatically subscribes the observer to the
+            dispatcher. Defaults to ``True``.
+        remove_completed_machine_nodes:
+            If ``True``, removes completed machine nodes from the graph.
+            Defaults to ``True``.
+        remove_completed_job_nodes:
+            If ``True``, removes completed job nodes from the graph.
+            Defaults to ``True``.
     """
 
     def __init__(
@@ -39,24 +54,6 @@ class ResidualGraphUpdater(GraphUpdater):
         remove_completed_machine_nodes: bool = True,
         remove_completed_job_nodes: bool = True,
     ):
-        """Initializes the residual graph updater.
-
-        Args:
-            dispatcher:
-                The dispatcher instance to observe.
-            job_shop_graph:
-                The job shop graph to update.
-            subscribe:
-                If True, automatically subscribes the observer to the
-                dispatcher. Defaults to True.
-            remove_completed_machine_nodes:
-                If True, removes completed machine nodes from the graph.
-                Defaults to True.
-            remove_completed_job_nodes:
-                If True, removes completed job nodes from the graph.
-                Defaults to True.
-        """
-
         self._is_completed_observer: None | IsCompletedObserver = None
         self.remove_completed_job_nodes = remove_completed_job_nodes
         self.remove_completed_machine_nodes = remove_completed_machine_nodes

job_shop_lib/reinforcement_learning/__init__.py

@@ -1,12 +1,24 @@
-"""Package for reinforcement learning components."""
+"""Contains reinforcement learning components.
+
+
+.. autosummary::
+
+    SingleJobShopGraphEnv
+    MultiJobShopGraphEnv
+    ObservationDict
+    ObservationSpaceKey
+    RewardObserver
+    MakespanReward
+    IdleTimeReward
+    RenderConfig
+    add_padding
+
+"""
 
 from job_shop_lib.reinforcement_learning._types_and_constants import (
     ObservationSpaceKey,
     RenderConfig,
     ObservationDict,
-    GanttChartWrapperConfig,
-    GifConfig,
-    VideoConfig,
 )
 
 from job_shop_lib.reinforcement_learning._reward_observers import (
@@ -30,9 +42,6 @@ __all__ = [
     "RewardObserver",
     "MakespanReward",
     "IdleTimeReward",
-    "GanttChartWrapperConfig",
-    "GifConfig",
-    "VideoConfig",
     "SingleJobShopGraphEnv",
     "RenderConfig",
     "ObservationDict",

job_shop_lib/reinforcement_learning/_multi_job_shop_graph_env.py

@@ -42,11 +42,11 @@ class MultiJobShopGraphEnv(gym.Env):
 
     The observation space includes:
 
-        - removed_nodes: Binary vector indicating removed nodes.
-        - edge_index: Edge list in COO format.
-        - operations: Matrix of operation features.
-        - jobs: Matrix of job features (if applicable).
-        - machines: Matrix of machine features (if applicable).
+    - removed_nodes: Binary vector indicating removed nodes.
+    - edge_index: Edge list in COO format.
+    - operations: Matrix of operation features.
+    - jobs: Matrix of job features (if applicable).
+    - machines: Matrix of machine features (if applicable).
 
     Internally, the class creates a
     :class:`~job_shop_lib.reinforcement_learning.SingleJobShopGraphEnv`
@@ -57,29 +57,37 @@ class MultiJobShopGraphEnv(gym.Env):
         instance_generator:
             A :class:`~job_shop_lib.generation.InstanceGenerator` that
             generates a new problem instance on each reset.
+
         action_space:
             :class:`gymnasium.spaces.Discrete`) action space with size equal to
             the maximum number of jobs.
+
         observation_space:
             Dictionary of observation spaces. Keys are defined in
             :class:`~job_shop_lib.reinforcement_learning.ObservationSpaceKey`.
+
         single_job_shop_graph_env:
             Environment for a specific Job Shop Scheduling Problem instance.
             See :class:`SingleJobShopGraphEnv`.
+
         graph_initializer:
             Function to create the initial graph representation. It should
             take a :class:`~job_shop_lib.JobShopInstance` as input and return
             a :class:`~job_shop_lib.graphs.JobShopGraph`.
+
         render_mode:
             Rendering mode for visualization. Supported modes are:
+
             - human: Renders the current Gannt chart.
             - save_video: Saves a video of the Gantt chart. Used only if the
               schedule is completed.
             - save_gif: Saves a GIF of the Gantt chart. Used only if the
               schedule is completed.
+
         render_config:
             Configuration for rendering. See
             :class:`~job_shop_lib.RenderConfig`.
+
         feature_observer_configs:
             List of :class:`~job_shop_lib.dispatching.DispatcherObserverConfig`
             for feature observers.
@@ -87,11 +95,63 @@ class MultiJobShopGraphEnv(gym.Env):
             Configuration for the reward function. See
             :class:`~job_shop_lib.dispatching.DispatcherObserverConfig` and
             :class:`~job_shop_lib.dispatching.RewardObserver`.
+
         graph_updater_config:
             Configuration for the graph updater. The graph updater is used to
             update the graph representation after each action. See
             :class:`~job_shop_lib.dispatching.DispatcherObserverConfig` and
             :class:`~job_shop_lib.graphs.GraphUpdater`.
+    Args:
+        instance_generator:
+            A :class:`~job_shop_lib.generation.InstanceGenerator` that
+            generates a new problem instance on each reset.
+
+        feature_observer_configs:
+            Configurations for feature observers. Each configuration
+            should be a
+            :class:`~job_shop_lib.dispatching.DispatcherObserverConfig`
+            with a class type that inherits from
+            :class:`~job_shop_lib.dispatching.FeatureObserver` or a string
+            or enum that represents a built-in feature observer.
+
+        graph_initializer:
+            Function to create the initial graph representation.
+            If ``None``, the default graph initializer is used:
+            :func:`~job_shop_lib.graphs.build_agent_task_graph`.
+        graph_updater_config:
+            Configuration for the graph updater. The graph updater is used
+            to update the graph representation after each action. If
+            ``None``, the default graph updater is used:
+            :class:`~job_shop_lib.graphs.ResidualGraphUpdater`.
+
+        ready_operations_filter:
+            Function to filter ready operations. If ``None``, the default
+            filter is used:
+            :func:`~job_shop_lib.dispatching.filter_dominated_operations`.
+
+        reward_function_config:
+            Configuration for the reward function. If ``None``, the default
+            reward function is used:
+            :class:`~job_shop_lib.dispatching.MakespanReward`.
+
+        render_mode:
+            Rendering mode for visualization. Supported modes are:
+
+            - human: Renders the current Gannt chart.
+            - save_video: Saves a video of the Gantt chart. Used only if
+                the schedule is completed.
+            - save_gif: Saves a GIF of the Gantt chart. Used only if the
+                schedule is completed.
+        render_config:
+            Configuration for rendering. See
+            :class:`~job_shop_lib.RenderConfig`.
+
+        use_padding:
+            Whether to use padding in observations. If True, all matrices
+            are padded to fixed sizes based on the maximum instance size.
+            Values are padded with -1, except for the "removed_nodes" key,
+            which is padded with ``True``, indicating that the node is
+            removed.
     """
 
     def __init__(
@@ -114,53 +174,6 @@ class MultiJobShopGraphEnv(gym.Env):
         render_config: RenderConfig | None = None,
         use_padding: bool = True,
     ) -> None:
-        """Initializes the environment.
-
-        Args:
-            instance_generator:
-                A :class:`~job_shop_lib.generation.InstanceGenerator` that
-                generates a new problem instance on each reset.
-            feature_observer_configs:
-                Configurations for feature observers. Each configuration
-                should be a
-                :class:`~job_shop_lib.dispatching.DispatcherObserverConfig`
-                with a class type that inherits from
-                :class:`~job_shop_lib.dispatching.FeatureObserver` or a string
-                or enum that represents a built-in feature observer.
-            graph_initializer:
-                Function to create the initial graph representation.
-                If ``None``, the default graph initializer is used:
-                :func:`~job_shop_lib.graphs.build_agent_task_graph`.
-            graph_updater_config:
-                Configuration for the graph updater. The graph updater is used
-                to update the graph representation after each action. If
-                ``None``, the default graph updater is used:
-                :class:`~job_shop_lib.graphs.ResidualGraphUpdater`.
-            ready_operations_filter:
-                Function to filter ready operations. If ``None``, the default
-                filter is used:
-                :func:`~job_shop_lib.dispatching.filter_dominated_operations`.
-            reward_function_config:
-                Configuration for the reward function. If ``None``, the default
-                reward function is used:
-                :class:`~job_shop_lib.dispatching.MakespanReward`.
-            render_mode:
-                Rendering mode for visualization. Supported modes are:
-                - human: Renders the current Gannt chart.
-                - save_video: Saves a video of the Gantt chart. Used only if
-                  the schedule is completed.
-                - save_gif: Saves a GIF of the Gantt chart. Used only if the
-                  schedule is completed.
-            render_config:
-                Configuration for rendering. See
-                :class:`~job_shop_lib.RenderConfig`.
-            use_padding:
-                Whether to use padding in observations. If True, all matrices
-                are padded to fixed sizes based on the maximum instance size.
-                Values are padded with -1, except for the "removed_nodes" key,
-                which is padded with ``True``, indicating that the node is
-                removed.
-        """
         super().__init__()
 
         # Create an instance with the maximum size
@@ -303,16 +316,15 @@ class MultiJobShopGraphEnv(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.
         """
         obs, reward, done, truncated, info = (
             self.single_job_shop_graph_env.step(action)