job-shop-lib 0.5.0__py3-none-any.whl → 1.0.0__py3-none-any.whl

job_shop_lib/generation/_general_instance_generator.py

@@ -0,0 +1,165 @@
+"""Home of the `BasicGenerator` class."""
+
+from typing import Optional, Tuple, Union
+import random
+
+from job_shop_lib import JobShopInstance
+from job_shop_lib.exceptions import ValidationError
+from job_shop_lib.generation import (
+    InstanceGenerator,
+    generate_duration_matrix,
+    generate_machine_matrix_with_recirculation,
+    generate_machine_matrix_without_recirculation,
+)
+
+
+class GeneralInstanceGenerator(InstanceGenerator):
+    """Generates instances for job shop problems.
+
+    This class is designed to be versatile, enabling the creation of various
+    job shop instances without the need for multiple dedicated classes.
+
+    It supports customization of the number of jobs, machines, operation
+    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.
+
+    The number of operations per machine is equal to the number of machines
+
+    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.
+        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.
+        allow_less_jobs_than_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.
+        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
+        self,
+        num_jobs: Union[int, Tuple[int, int]] = (10, 20),
+        num_machines: Union[int, Tuple[int, int]] = (5, 10),
+        duration_range: Tuple[int, int] = (1, 99),
+        allow_less_jobs_than_machines: bool = True,
+        allow_recirculation: bool = False,
+        machines_per_operation: Union[int, Tuple[int, int]] = 1,
+        name_suffix: str = "classic_generated_instance",
+        seed: Optional[int] = None,
+        iteration_limit: Optional[int] = None,
+    ):
+        super().__init__(
+            num_jobs=num_jobs,
+            num_machines=num_machines,
+            duration_range=duration_range,
+            name_suffix=name_suffix,
+            seed=seed,
+            iteration_limit=iteration_limit,
+        )
+        if isinstance(machines_per_operation, int):
+            machines_per_operation = (
+                machines_per_operation,
+                machines_per_operation,
+            )
+        if machines_per_operation != (1, 1):
+            raise NotImplementedError(
+                "The number of machines per operation must be 1 for now."
+            )
+        self.machines_per_operation = machines_per_operation
+
+        self.allow_less_jobs_than_machines = allow_less_jobs_than_machines
+        self.allow_recirculation = allow_recirculation
+        self.name_suffix = name_suffix
+
+        if seed is not None:
+            random.seed(seed)
+
+    def __repr__(self) -> str:
+        return (
+            f"GeneralInstanceGenerator("
+            f"num_jobs_range={self.num_jobs_range}, "
+            f"num_machines_range={self.num_machines_range}, "
+            f"duration_range={self.duration_range})"
+        )
+
+    def generate(
+        self,
+        num_jobs: Optional[int] = None,
+        num_machines: Optional[int] = None,
+    ) -> JobShopInstance:
+        if num_jobs is None:
+            num_jobs = random.randint(*self.num_jobs_range)
+
+        if num_machines is None:
+            min_num_machines, max_num_machines = self.num_machines_range
+            if not self.allow_less_jobs_than_machines:
+                min_num_machines = min(num_jobs, max_num_machines)
+            num_machines = random.randint(min_num_machines, max_num_machines)
+        elif (
+            not self.allow_less_jobs_than_machines and num_jobs < num_machines
+        ):
+            raise ValidationError(
+                "There are fewer jobs than machines, which is not allowed "
+                " when `allow_less_jobs_than_machines` attribute is False."
+            )
+
+        duration_matrix = generate_duration_matrix(
+            num_jobs, num_machines, self.duration_range
+        )
+        if self.allow_recirculation:
+            machine_matrix = generate_machine_matrix_with_recirculation(
+                num_jobs, num_machines
+            )
+        else:
+            machine_matrix = generate_machine_matrix_without_recirculation(
+                num_jobs, num_machines
+            )
+
+        return JobShopInstance.from_matrices(
+            duration_matrix.tolist(),
+            machine_matrix.tolist(),
+            name=self._next_name(),
+        )

job_shop_lib/generation/_instance_generator.py

@@ -0,0 +1,133 @@
+"""Home of the `InstanceGenerator` class."""
+
+import abc
+
+import random
+from typing import Iterator, Optional, Tuple, Union
+
+from job_shop_lib import JobShopInstance
+from job_shop_lib.exceptions import UninitializedAttributeError
+
+
+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.
+
+    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
+        self,
+        num_jobs: Union[int, Tuple[int, int]] = (10, 20),
+        num_machines: Union[int, Tuple[int, int]] = (5, 10),
+        duration_range: Tuple[int, int] = (1, 99),
+        name_suffix: str = "generated_instance",
+        seed: Optional[int] = None,
+        iteration_limit: Optional[int] = None,
+    ):
+        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,
+        num_jobs: Optional[int] = None,
+        num_machines: Optional[int] = None,
+    ) -> JobShopInstance:
+        """Generates a single job shop instance
+
+        Args:
+            num_jobs: The number of jobs to generate. If None, a random value
+                within the specified range will be used.
+            num_machines: The number of machines to generate. If None, a random
+                value within the specified range will be used.
+        """
+
+    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 UninitializedAttributeError("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/{generators/transformations.py → generation/_transformations.py}

@@ -3,6 +3,7 @@
 import abc
 import copy
 import random
+from typing import Optional
 
 from job_shop_lib import JobShopInstance, Operation
 
@@ -38,7 +39,7 @@ 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):
+    def __init__(self, num_machines: int, suffix: Optional[str] = None):
         if suffix is None:
             suffix = f"_machines={num_machines}"
         super().__init__(suffix=suffix)
@@ -83,7 +84,7 @@ class AddDurationNoise(Transformation):
         min_duration: int = 1,
         max_duration: int = 100,
         noise_level: int = 10,
-        suffix: str | None = None,
+        suffix: Optional[str] = None,
     ):
         if suffix is None:
             suffix = f"_noise={noise_level}"
@@ -111,22 +112,25 @@ 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,
         min_jobs: int,
         max_jobs: int,
-        target_jobs: int | None = None,
-        suffix: str | None = None,
+        target_jobs: Optional[int] = None,
+        suffix: Optional[str] = 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/generation/_utils.py

@@ -0,0 +1,124 @@
+from typing import Tuple
+import numpy as np
+from numpy.typing import NDArray
+
+from job_shop_lib.exceptions import ValidationError
+
+
+def generate_duration_matrix(
+    num_jobs: int, num_machines: int, duration_range: Tuple[int, int]
+) -> NDArray[np.int32]:
+    """Generates a duration matrix.
+
+    Args:
+        num_jobs: The number of jobs.
+        num_machines: The number of machines.
+        duration_range: The range of the duration values.
+
+    Returns:
+        A duration matrix with shape (num_jobs, num_machines).
+    """
+    if duration_range[0] > duration_range[1]:
+        raise ValidationError(
+            "The lower bound of the duration range must be less than or equal "
+            "to the upper bound."
+        )
+    if num_jobs <= 0:
+        raise ValidationError("The number of jobs must be greater than 0.")
+    if num_machines <= 0:
+        raise ValidationError("The number of machines must be greater than 0.")
+
+    return np.random.randint(
+        duration_range[0],
+        duration_range[1] + 1,
+        size=(num_jobs, num_machines),
+        dtype=np.int32,
+    )
+
+
+def generate_machine_matrix_with_recirculation(
+    num_jobs: int, num_machines: int
+) -> NDArray[np.int32]:
+    """Generate a machine matrix with recirculation.
+
+    Args:
+        num_jobs: The number of jobs.
+        num_machines: The number of machines.
+
+    Returns:
+        A machine matrix with recirculation with shape (num_machines,
+        num_jobs).
+    """
+    if num_jobs <= 0:
+        raise ValidationError("The number of jobs must be greater than 0.")
+    if num_machines <= 0:
+        raise ValidationError("The number of machines must be greater than 0.")
+    num_machines_is_correct = False
+    while not num_machines_is_correct:
+        machine_matrix: np.ndarray = np.random.randint(
+            0, num_machines, size=(num_machines, num_jobs)
+        )
+        num_machines_is_correct = (
+            len(np.unique(machine_matrix)) == num_machines
+        )
+
+    return machine_matrix
+
+
+def generate_machine_matrix_without_recirculation(
+    num_jobs: int, num_machines: int
+) -> NDArray[np.int32]:
+    """Generate a machine matrix without recirculation.
+
+    Args:
+        num_jobs: The number of jobs.
+        num_machines: The number of machines.
+
+    Returns:
+        A machine matrix without recirculation.
+    """
+    if num_jobs <= 0:
+        raise ValidationError("The number of jobs must be greater than 0.")
+    if num_machines <= 0:
+        raise ValidationError("The number of machines must be greater than 0.")
+    # Start with an arange repeated:
+    # m1: [0, 1, 2]
+    # m2: [0, 1, 2]
+    # m3: [0, 1, 2]
+    machine_matrix = np.tile(
+        np.arange(num_machines).reshape(1, num_machines),
+        (num_jobs, 1),
+    )
+    # Shuffle the columns:
+    machine_matrix = np.apply_along_axis(
+        np.random.permutation, 1, machine_matrix
+    )
+    return machine_matrix
+
+
+if __name__ == "__main__":
+
+    NUM_JOBS = 3
+    NUM_MACHINES = 3
+    DURATION_RANGE = (1, 10)
+
+    duration_matrix = generate_duration_matrix(
+        num_jobs=NUM_JOBS,
+        num_machines=NUM_MACHINES,
+        duration_range=DURATION_RANGE,
+    )
+    print(duration_matrix)
+
+    machine_matrix_with_recirculation = (
+        generate_machine_matrix_with_recirculation(
+            num_jobs=NUM_JOBS, num_machines=NUM_MACHINES
+        )
+    )
+    print(machine_matrix_with_recirculation)
+
+    machine_matrix_without_recirculation = (
+        generate_machine_matrix_without_recirculation(
+            num_jobs=NUM_JOBS, num_machines=NUM_MACHINES
+        )
+    )
+    print(machine_matrix_without_recirculation)

job_shop_lib/graphs/__init__.py

@@ -1,19 +1,34 @@
-"""Package for graph related classes and functions."""
+"""Package for graph related classes and functions.
 
-from job_shop_lib.graphs.constants import EdgeType, NodeType
-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 (
+The main classes and functions available in this package are:
+
+.. autosummary::
+    JobShopGraph
+    Node
+    NodeType
+    build_disjunctive_graph
+    build_solved_disjunctive_graph
+    build_resource_task_graph
+    build_complete_resource_task_graph
+    build_resource_task_graph_with_jobs
+
+"""
+
+from job_shop_lib.graphs._constants import EdgeType, NodeType
+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,
     add_source_sink_edges,
 )
-from job_shop_lib.graphs.build_agent_task_graph import (
-    build_agent_task_graph,
-    build_complete_agent_task_graph,
-    build_agent_task_graph_with_jobs,
+from job_shop_lib.graphs._build_resource_task_graphs import (
+    build_resource_task_graph,
+    build_complete_resource_task_graph,
+    build_resource_task_graph_with_jobs,
     add_same_job_operations_edges,
     add_machine_nodes,
     add_operation_machine_edges,
@@ -23,6 +38,7 @@ from job_shop_lib.graphs.build_agent_task_graph import (
     add_global_node,
     add_machine_global_edges,
     add_job_global_edges,
+    add_job_job_edges,
 )
 
 
@@ -37,9 +53,9 @@ __all__ = [
     "add_conjunctive_edges",
     "add_source_sink_nodes",
     "add_source_sink_edges",
-    "build_agent_task_graph",
-    "build_complete_agent_task_graph",
-    "build_agent_task_graph_with_jobs",
+    "build_resource_task_graph",
+    "build_complete_resource_task_graph",
+    "build_resource_task_graph_with_jobs",
     "add_same_job_operations_edges",
     "add_machine_nodes",
     "add_operation_machine_edges",
@@ -49,4 +65,6 @@ __all__ = [
     "add_global_node",
     "add_machine_global_edges",
     "add_job_global_edges",
+    "build_solved_disjunctive_graph",
+    "add_job_job_edges",
 ]

job_shop_lib/graphs/{build_disjunctive_graph.py → _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."""