job-shop-lib 0.4.0__py3-none-any.whl → 0.5.1__py3-none-any.whl

job_shop_lib/generation/instance_generator.py

@@ -0,0 +1,122 @@
+import abc
+
+import random
+from typing import Iterator
+
+from job_shop_lib import JobShopInstance
+
+
+class InstanceGenerator(abc.ABC):
+    """Common interface for all generators.
+
+    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.
+
+    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.
+
+    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.
+        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.
+        name_suffix:
+            A suffix to append to each instance's name for identification.
+        seed:
+            Seed for the random number generator to ensure reproducibility.
+    """
+
+    def __init__(  # pylint: disable=too-many-arguments
+        self,
+        num_jobs: int | tuple[int, int] = (10, 20),
+        num_machines: int | tuple[int, int] = (5, 10),
+        duration_range: tuple[int, int] = (1, 99),
+        name_suffix: str = "generated_instance",
+        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):
+            num_machines = (num_machines, num_machines)
+        if seed is not None:
+            random.seed(seed)
+
+        self.num_jobs_range = num_jobs
+        self.num_machines_range = num_machines
+        self.duration_range = duration_range
+        self.name_suffix = name_suffix
+
+        self._counter = 0
+        self._current_iteration = 0
+        self._iteration_limit = iteration_limit
+
+    @abc.abstractmethod
+    def generate(self) -> JobShopInstance:
+        """Generates a single job shop instance"""
+
+    def _next_name(self) -> str:
+        self._counter += 1
+        return f"{self.name_suffix}_{self._counter}"
+
+    def __iter__(self) -> Iterator[JobShopInstance]:
+        self._current_iteration = 0
+        return self
+
+    def __next__(self) -> JobShopInstance:
+        if (
+            self._iteration_limit is not None
+            and self._current_iteration >= self._iteration_limit
+        ):
+            raise StopIteration
+        self._current_iteration += 1
+        return self.generate()
+
+    def __len__(self) -> int:
+        if self._iteration_limit is None:
+            raise ValueError("Iteration limit is not set.")
+        return self._iteration_limit
+
+    @property
+    def max_num_jobs(self) -> int:
+        """Returns the maximum number of jobs that can be generated."""
+        return self.num_jobs_range[1]
+
+    @property
+    def min_num_jobs(self) -> int:
+        """Returns the minimum number of jobs that can be generated."""
+        return self.num_jobs_range[0]
+
+    @property
+    def max_num_machines(self) -> int:
+        """Returns the maximum number of machines that can be generated."""
+        return self.num_machines_range[1]
+
+    @property
+    def min_num_machines(self) -> int:
+        """Returns the minimum number of machines that can be generated."""
+        return self.num_machines_range[0]

job_shop_lib/generation/transformations.py

@@ -0,0 +1,164 @@
+"""Classes for generating transformed JobShopInstance objects."""
+
+import abc
+import copy
+import random
+
+from job_shop_lib import JobShopInstance, Operation
+
+
+class Transformation(abc.ABC):
+    """Base class for transformations applied to JobShopInstance objects."""
+
+    def __init__(self, suffix: str = ""):
+        self.suffix = suffix
+        self.counter = 0
+
+    @abc.abstractmethod
+    def apply(self, instance: JobShopInstance) -> JobShopInstance:
+        """Applies the transformation to a given JobShopInstance.
+
+        Args:
+            instance: The JobShopInstance to transform.
+
+        Returns:
+            A new JobShopInstance with the transformation applied.
+        """
+
+    def __call__(self, instance: JobShopInstance) -> JobShopInstance:
+        instance = self.apply(instance)
+        suffix = f"{self.suffix}_id={self.counter}"
+        instance.name += suffix
+        self.counter += 1
+        return instance
+
+
+# pylint: disable=too-few-public-methods
+class RemoveMachines(Transformation):
+    """Removes operations associated with randomly selected machines until
+    there are exactly num_machines machines left."""
+
+    def __init__(self, num_machines: int, suffix: str | None = None):
+        if suffix is None:
+            suffix = f"_machines={num_machines}"
+        super().__init__(suffix=suffix)
+        self.num_machines = num_machines
+
+    def apply(self, instance: JobShopInstance) -> JobShopInstance:
+        if instance.num_machines <= self.num_machines:
+            return instance  # No need to remove machines
+
+        # Select machine indices to keep
+        machines_to_keep = set(
+            random.sample(range(instance.num_machines), self.num_machines)
+        )
+
+        # Re-index machines
+        machine_reindex_map = {
+            old_id: new_id
+            for new_id, old_id in enumerate(sorted(machines_to_keep))
+        }
+
+        new_jobs = []
+        for job in instance.jobs:
+            # Keep operations whose machine_id is in machines_to_keep and
+            # re-index them
+            new_jobs.append(
+                [
+                    Operation(machine_reindex_map[op.machine_id], op.duration)
+                    for op in job
+                    if op.machine_id in machines_to_keep
+                ]
+            )
+
+        return JobShopInstance(new_jobs, instance.name)
+
+
+# pylint: disable=too-few-public-methods
+class AddDurationNoise(Transformation):
+    """Adds uniform integer noise to operation durations."""
+
+    def __init__(
+        self,
+        min_duration: int = 1,
+        max_duration: int = 100,
+        noise_level: int = 10,
+        suffix: str | None = None,
+    ):
+        if suffix is None:
+            suffix = f"_noise={noise_level}"
+        super().__init__(suffix=suffix)
+        self.min_duration = min_duration
+        self.max_duration = max_duration
+        self.noise_level = noise_level
+
+    def apply(self, instance: JobShopInstance) -> JobShopInstance:
+        new_jobs = []
+        for job in instance.jobs:
+            new_job = []
+            for op in job:
+                noise = random.randint(-self.noise_level, self.noise_level)
+                new_duration = max(
+                    self.min_duration,
+                    min(self.max_duration, op.duration + noise),
+                )
+
+                new_job.append(Operation(op.machine_id, new_duration))
+            new_jobs.append(new_job)
+
+        return JobShopInstance(new_jobs, instance.name)
+
+
+class RemoveJobs(Transformation):
+    """Removes jobs randomly until the number of jobs is within a specified
+    range."""
+
+    def __init__(
+        self,
+        min_jobs: int,
+        max_jobs: int,
+        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)
+        self.min_jobs = min_jobs
+        self.max_jobs = max_jobs
+        self.target_jobs = target_jobs
+
+    def apply(self, instance: JobShopInstance) -> JobShopInstance:
+        if self.target_jobs is None:
+            target_jobs = random.randint(self.min_jobs, self.max_jobs)
+        else:
+            target_jobs = self.target_jobs
+        new_jobs = copy.deepcopy(instance.jobs)
+
+        while len(new_jobs) > target_jobs:
+            new_jobs.pop(random.randint(0, len(new_jobs) - 1))
+
+        return JobShopInstance(new_jobs, instance.name)
+
+    @staticmethod
+    def remove_job(
+        instance: JobShopInstance, job_index: int
+    ) -> JobShopInstance:
+        """Removes a specific job from the instance.
+
+        Args:
+            instance: The JobShopInstance from which to remove the job.
+            job_index: The index of the job to remove.
+
+        Returns:
+            A new JobShopInstance with the specified job removed.
+        """
+        new_jobs = copy.deepcopy(instance.jobs)
+        new_jobs.pop(job_index)
+        return JobShopInstance(new_jobs, instance.name)

job_shop_lib/generators/__init__.py

@@ -1,4 +1,5 @@
-"""Package for generating job shop instances."""
+"""DEPRECATED: Use `job_shop_lib.generation` instead. It will be removed in
+version 1.0.0."""
 
 from job_shop_lib.generators.basic_generator import BasicGenerator
 

job_shop_lib/generators/basic_generator.py

@@ -9,6 +9,9 @@ from job_shop_lib import JobShopInstance, Operation
 class BasicGenerator:  # pylint: disable=too-many-instance-attributes
     """Generates instances for job shop problems.
 
+    DEPRECATED: Class moved to `job_shop_lib.generation` and renamed to
+    `GeneralInstanceGenerator`. This class will be removed in version 1.0.0.
+
     This class is designed to be versatile, enabling the creation of various
     job shop instances without the need for multiple dedicated classes.
 

job_shop_lib/graphs/build_disjunctive_graph.py

@@ -23,6 +23,26 @@ 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.
+    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
+    source and sink nodes with their respective edges to and from all other
+    operations.
+
+    Edges have a "type" attribute indicating whether they are disjunctive or
+    conjunctive.
+
+    Args:
+        instance (JobShopInstance): The job shop instance for which to build
+        the graph.
+
+    Returns:
+        JobShopGraph: A JobShopGraph object representing the disjunctive graph
+        of the job shop scheduling problem.
+    """
     graph = JobShopGraph(instance)
     add_disjunctive_edges(graph)
     add_conjunctive_edges(graph)

job_shop_lib/job_shop_instance.py

@@ -6,6 +6,8 @@ import os
 import functools
 from typing import Any
 
+import numpy as np
+
 from job_shop_lib import Operation
 
 
@@ -264,6 +266,58 @@ class JobShopInstance:
             [operation.machine_id for operation in job] for job in self.jobs
         ]
 
+    @functools.cached_property
+    def durations_matrix_array(self) -> np.ndarray:
+        """Returns the duration matrix of the instance as a numpy array.
+
+        The returned array has shape (num_jobs, max_num_operations_per_job).
+        Non-existing operations are filled with np.nan.
+
+        Example:
+            >>> jobs = [[Operation(0, 2), Operation(1, 3)], [Operation(0, 4)]]
+            >>> instance = JobShopInstance(jobs)
+            >>> instance.durations_matrix_array
+            array([[ 2.,  2.],
+                   [ 4., nan]], dtype=float32)
+        """
+        duration_matrix = self.durations_matrix
+        return self._fill_matrix_with_nans_2d(duration_matrix)
+
+    @functools.cached_property
+    def machines_matrix_array(self) -> np.ndarray:
+        """Returns the machines matrix of the instance as a numpy array.
+
+        The returned array has shape (num_jobs, max_num_operations_per_job,
+        max_num_machines_per_operation). Non-existing machines are filled with
+        np.nan.
+
+        Example:
+            >>> jobs = [
+            ...     [Operation(machines=[0, 1], 2), Operation(machines=1, 3)],
+            ...     [Operation(machines=0, 6)],
+            ... ]
+            >>> instance = JobShopInstance(jobs)
+            >>> instance.machines_matrix_array
+            array([[[ 0.,  1.],
+                    [ 1., nan]],
+                   [[ 0., nan],
+                    [nan, nan]]], dtype=float32)
+        """
+
+        machines_matrix = self.machines_matrix
+        if self.is_flexible:
+            # False positive from mypy, the type of machines_matrix is
+            # list[list[list[int]]] here
+            return self._fill_matrix_with_nans_3d(
+                machines_matrix  # type: ignore[arg-type]
+            )
+
+        # False positive from mypy, the type of machines_matrix is
+        # list[list[int]] here
+        return self._fill_matrix_with_nans_2d(
+            machines_matrix  # type: ignore[arg-type]
+        )
+
     @functools.cached_property
     def operations_by_machine(self) -> list[list[Operation]]:
         """Returns a list of lists of operations.
@@ -353,3 +407,50 @@ class JobShopInstance:
     def total_duration(self) -> int:
         """Returns the sum of the durations of all operations in all jobs."""
         return sum(self.job_durations)
+
+    @staticmethod
+    def _fill_matrix_with_nans_2d(matrix: list[list[int]]) -> np.ndarray:
+        """Fills a matrix with np.nan values.
+
+        Args:
+            matrix:
+                A list of lists of integers.
+
+        Returns:
+            A numpy array with the same shape as the input matrix, filled with
+            np.nan values.
+        """
+        max_length = max(len(row) for row in matrix)
+        squared_matrix = np.full(
+            (len(matrix), max_length), np.nan, dtype=np.float32
+        )
+        for i, row in enumerate(matrix):
+            squared_matrix[i, : len(row)] = row
+        return squared_matrix
+
+    @staticmethod
+    def _fill_matrix_with_nans_3d(matrix: list[list[list[int]]]) -> np.ndarray:
+        """Fills a 3D matrix with np.nan values.
+
+        Args:
+            matrix:
+                A list of lists of lists of integers.
+
+        Returns:
+            A numpy array with the same shape as the input matrix, filled with
+            np.nan values.
+        """
+        max_length = max(len(row) for row in matrix)
+        max_inner_length = len(matrix[0][0])
+        for row in matrix:
+            for inner_row in row:
+                max_inner_length = max(max_inner_length, len(inner_row))
+        squared_matrix = np.full(
+            (len(matrix), max_length, max_inner_length),
+            np.nan,
+            dtype=np.float32,
+        )
+        for i, row in enumerate(matrix):
+            for j, inner_row in enumerate(row):
+                squared_matrix[i, j, : len(inner_row)] = inner_row
+        return squared_matrix

job_shop_lib/visualization/create_gif.py

@@ -27,7 +27,8 @@ def create_gif(
     instance: JobShopInstance,
     solver: DispatchingRuleSolver,
     plot_function: (
-        Callable[[Schedule, int, list[Operation] | None], Figure] | None
+        Callable[[Schedule, int, list[Operation] | None, int | None], Figure]
+        | None
     ) = None,
     fps: int = 1,
     remove_frames: bool = True,
@@ -80,50 +81,59 @@ def plot_gantt_chart_wrapper(
     title: str | None = None,
     cmap: str = "viridis",
     show_available_operations: bool = False,
-) -> Callable[[Schedule, int, list[Operation] | None], Figure]:
+) -> Callable[[Schedule, int, list[Operation] | None, int | None], Figure]:
     """Returns a function that plots a Gantt chart for an unfinished schedule.
 
     Args:
         title: The title of the Gantt chart.
         cmap: The name of the colormap to use.
+        show_available_operations:
+            Whether to show the available operations in the Gantt chart.
 
     Returns:
         A function that plots a Gantt chart for a schedule. The function takes
-        a `Schedule` object and the makespan of the schedule as input and
-        returns a `Figure` object.
+        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.
     """
 
     def plot_function(
         schedule: Schedule,
         makespan: int,
         available_operations: list | None = None,
+        current_time: int | None = None,
     ) -> Figure:
         fig, ax = plot_gantt_chart(
             schedule, title=title, cmap_name=cmap, xlim=makespan
         )
 
-        if not show_available_operations or available_operations is None:
-            return fig
-
-        operations_text = "\n".join(
-            str(operation) for operation in available_operations
-        )
-        text = f"Available operations:\n{operations_text}"
-        # Print the available operations at the bottom right corner
-        # of the Gantt chart
-        fig.text(
-            1.25,
-            0.05,
-            text,
-            ha="right",
-            va="bottom",
-            transform=ax.transAxes,
-            bbox={
-                "facecolor": "white",
-                "alpha": 0.5,
-                "boxstyle": "round,pad=0.5",
-            },
-        )
+        if show_available_operations and available_operations is not None:
+
+            operations_text = "\n".join(
+                str(operation) for operation in available_operations
+            )
+            text = f"Available operations:\n{operations_text}"
+            # Print the available operations at the bottom right corner
+            # of the Gantt chart
+            fig.text(
+                1.25,
+                0.05,
+                text,
+                ha="right",
+                va="bottom",
+                transform=ax.transAxes,
+                bbox={
+                    "facecolor": "white",
+                    "alpha": 0.5,
+                    "boxstyle": "round,pad=0.5",
+                },
+            )
+        if current_time is not None:
+            ax.axvline(current_time, color="red", linestyle="--")
         return fig
 
     return plot_function
@@ -133,7 +143,9 @@ def create_gantt_chart_frames(
     frames_dir: str,
     instance: JobShopInstance,
     solver: DispatchingRuleSolver,
-    plot_function: Callable[[Schedule, int, list[Operation] | None], Figure],
+    plot_function: Callable[
+        [Schedule, int, list[Operation] | None, int | None], Figure
+    ],
     plot_current_time: bool = True,
 ) -> None:
     """Creates frames of the Gantt chart for the schedule being built.
@@ -150,7 +162,8 @@ def create_gantt_chart_frames(
             should take a `Schedule` object and the makespan of the schedule as
             input and return a `Figure` object.
         plot_current_time:
-            Whether to plot a vertical line at the current time."""
+            Whether to plot a vertical line at the current time.
+    """
     dispatcher = Dispatcher(instance, pruning_function=solver.pruning_function)
     history_tracker = HistoryTracker(dispatcher)
     makespan = solver.solve(instance, dispatcher).makespan()
@@ -160,23 +173,19 @@ def create_gantt_chart_frames(
         dispatcher.dispatch(
             scheduled_operation.operation, scheduled_operation.machine_id
         )
+        current_time = (
+            None if not plot_current_time else dispatcher.current_time()
+        )
         fig = plot_function(
             dispatcher.schedule,
             makespan,
             dispatcher.available_operations(),
+            current_time,
         )
-        current_time = (
-            None if not plot_current_time else dispatcher.current_time()
-        )
-        _save_frame(fig, frames_dir, i, current_time)
-
+        _save_frame(fig, frames_dir, i)
 
-def _save_frame(
-    figure: Figure, frames_dir: str, number: int, current_time: int | None
-) -> None:
-    if current_time is not None:
-        figure.gca().axvline(current_time, color="red", linestyle="--")
 
+def _save_frame(figure: Figure, frames_dir: str, number: int) -> None:
     figure.savefig(f"{frames_dir}/frame_{number:02d}.png", bbox_inches="tight")
     plt.close(figure)
 

job_shop_lib/visualization/gantt_chart.py

@@ -65,7 +65,7 @@ def _plot_machine_schedules(
 ) -> dict[int, Patch]:
     """Plots the schedules for each machine."""
     max_job_id = schedule.instance.num_jobs - 1
-    cmap = plt.cm.get_cmap(cmap_name, max_job_id + 1)
+    cmap = plt.get_cmap(cmap_name, max_job_id + 1)
     norm = Normalize(vmin=0, vmax=max_job_id)
     legend_handles = {}
 

{job_shop_lib-0.4.0.dist-info → job_shop_lib-0.5.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: job-shop-lib
-Version: 0.4.0
+Version: 0.5.1
 Summary: An easy-to-use and modular Python library for the Job Shop Scheduling Problem (JSSP)
 License: MIT
 Author: Pabloo22
@@ -15,7 +15,8 @@ Provides-Extra: pygraphviz
 Requires-Dist: imageio (>=2,<3)
 Requires-Dist: matplotlib (>=3,<4)
 Requires-Dist: networkx (>=3,<4)
-Requires-Dist: ortools (>=9,<10)
+Requires-Dist: numpy (>=1.26.4,<2.0.0)
+Requires-Dist: ortools (>=9.9,<9.10)
 Requires-Dist: pyarrow (>=15.0.0,<16.0.0)
 Requires-Dist: pygraphviz (>=1.12,<2.0) ; extra == "pygraphviz"
 Description-Content-Type: text/markdown
@@ -83,7 +84,7 @@ ft06 = load_benchmark_instance("ft06")
 ```
 
 The module `benchmarks` contains functions to load the instances from the file and return them as `JobShopInstance` objects without having to download them
-manually. The instances are stored in [benchmark_instances.json](job_shop_lib/benchmarks/benchmark_instances.json).
+manually.
 
 The contributions to this benchmark dataset are as follows:
 
@@ -171,13 +172,15 @@ class DispatchingRule(str, Enum):
 We can visualize the solution with a `DispatchingRuleSolver` as a gif:
 
 ```python
-from job_shop_lib.visualization import create_gif, get_plot_function
+from job_shop_lib.visualization import create_gif, plot_gantt_chart_wrapper
 from job_shop_lib.dispatching import DispatchingRuleSolver, DispatchingRule
 
 plt.style.use("ggplot")
 
 mwkr_solver = DispatchingRuleSolver("most_work_remaining")
-plot_function = get_plot_function(title="Solution with Most Work Remaining Rule")
+plot_function = plot_gantt_chart_wrapper(
+    title="Solution with Most Work Remaining Rule"
+)
 create_gif(
     gif_path="ft06_optimized.gif",
     instance=ft06,
@@ -350,3 +353,4 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
      Journal of Operational Research, vol. 64, no. 2, pp. 278–285, 1993.
 
 - Park, Junyoung, Sanjar Bakhtiyar, and Jinkyoo Park. "ScheduleNet: Learn to solve multi-agent scheduling problems with reinforcement learning." arXiv preprint arXiv:2106.03051, 2021. 
+