job-shop-lib 0.5.1__py3-none-any.whl → 1.0.0a1__py3-none-any.whl

job_shop_lib/dispatching/{dispatching_rules.py → rules/_dispatching_rules_functions.py}

@@ -6,17 +6,22 @@ which operations are selected for execution based on certain criteria such as
 shortest processing time, first come first served, etc.
 """
 
-from typing import Callable
+from collections.abc import Callable, Sequence
 import random
 
 from job_shop_lib import Operation
-from job_shop_lib.dispatching import Dispatcher
+from job_shop_lib.dispatching import Dispatcher, DispatcherObserver
+from job_shop_lib.dispatching.feature_observers import (
+    DurationObserver,
+    FeatureType,
+    IsReadyObserver,
+)
 
 
 def shortest_processing_time_rule(dispatcher: Dispatcher) -> Operation:
     """Dispatches the operation with the shortest duration."""
     return min(
-        dispatcher.available_operations(),
+        dispatcher.ready_operations(),
         key=lambda operation: operation.duration,
     )
 
@@ -24,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.available_operations(),
+        dispatcher.ready_operations(),
         key=lambda operation: operation.position_in_job,
     )
 
@@ -32,11 +37,11 @@ def first_come_first_served_rule(dispatcher: Dispatcher) -> Operation:
 def most_work_remaining_rule(dispatcher: Dispatcher) -> Operation:
     """Dispatches the operation which job has the most remaining work."""
     job_remaining_work = [0] * dispatcher.instance.num_jobs
-    for operation in dispatcher.uncompleted_operations():
+    for operation in dispatcher.unscheduled_operations():
         job_remaining_work[operation.job_id] += operation.duration
 
     return max(
-        dispatcher.available_operations(),
+        dispatcher.ready_operations(),
         key=lambda operation: job_remaining_work[operation.job_id],
     )
 
@@ -48,18 +53,18 @@ def most_operations_remaining_rule(dispatcher: Dispatcher) -> Operation:
         job_remaining_operations[operation.job_id] += 1
 
     return max(
-        dispatcher.available_operations(),
+        dispatcher.ready_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.available_operations())
+    return random.choice(dispatcher.ready_operations())
 
 
 def score_based_rule(
-    score_function: Callable[[Dispatcher], list[int]]
+    score_function: Callable[[Dispatcher], Sequence[float]]
 ) -> Callable[[Dispatcher], Operation]:
     """Creates a dispatching rule based on a scoring function.
 
@@ -75,7 +80,7 @@ def score_based_rule(
     def rule(dispatcher: Dispatcher) -> Operation:
         scores = score_function(dispatcher)
         return max(
-            dispatcher.available_operations(),
+            dispatcher.ready_operations(),
             key=lambda operation: scores[operation.job_id],
         )
 
@@ -83,7 +88,7 @@ def score_based_rule(
 
 
 def score_based_rule_with_tie_breaker(
-    score_functions: list[Callable[[Dispatcher], list[int]]],
+    score_functions: list[Callable[[Dispatcher], Sequence[int]]],
 ) -> Callable[[Dispatcher], Operation]:
     """Creates a dispatching rule based on multiple scoring functions.
 
@@ -97,7 +102,7 @@ def score_based_rule_with_tie_breaker(
     """
 
     def rule(dispatcher: Dispatcher) -> Operation:
-        candidates = dispatcher.available_operations()
+        candidates = dispatcher.ready_operations()
         for scoring_function in score_functions:
             scores = scoring_function(dispatcher)
             best_score = max(scores)
@@ -121,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.available_operations():
+    for operation in dispatcher.ready_operations():
         scores[operation.job_id] = -operation.duration
     return scores
 
@@ -130,18 +135,66 @@ 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.available_operations():
+    for operation in dispatcher.ready_operations():
         scores[operation.job_id] = operation.operation_id
     return scores
 
 
-def most_work_remaining_score(dispatcher: Dispatcher) -> list[int]:
-    """Scores each job based on the remaining work in the job."""
-    num_jobs = dispatcher.instance.num_jobs
-    scores = [0] * num_jobs
-    for operation in dispatcher.uncompleted_operations():
-        scores[operation.job_id] += operation.duration
-    return scores
+class MostWorkRemainingScorer:  # pylint: disable=too-few-public-methods
+    """Scores each job based on the remaining work in the job.
+
+    This class is conceptually a function: it can be called with a
+    :class:`~job_shop_lib.dispatching.Dispatcher` instance as input, and it
+    returns a list of scores for each job. The reason for using a class instead
+    of a function is to cache the observers that are created for each
+    dispatcher instance. This way, the observers do not have to be retrieved
+    every time the function is called.
+
+    """
+
+    def __init__(self) -> None:
+        self._duration_observer: DurationObserver | None = None
+        self._is_ready_observer: IsReadyObserver | None = None
+        self._current_dispatcher: Dispatcher | None = None
+
+    def __call__(self, dispatcher: Dispatcher) -> Sequence[int]:
+        """Scores each job based on the remaining work in the job."""
+
+        if self._current_dispatcher is not dispatcher:
+            self._duration_observer = None
+            self._is_ready_observer = None
+            self._current_dispatcher = dispatcher
+
+        def has_job_feature(observer: DispatcherObserver) -> bool:
+            if not isinstance(observer, DurationObserver):
+                return False
+            return FeatureType.JOBS in observer.features
+
+        if self._duration_observer is None:
+            self._duration_observer = dispatcher.create_or_get_observer(
+                DurationObserver,
+                condition=has_job_feature,
+                feature_types=FeatureType.JOBS,
+            )
+        if self._is_ready_observer is None:
+            self._is_ready_observer = dispatcher.create_or_get_observer(
+                IsReadyObserver,
+                condition=has_job_feature,
+                feature_types=FeatureType.JOBS,
+            )
+
+        work_remaining = self._duration_observer.features[
+            FeatureType.JOBS
+        ].copy()
+        is_ready = self._is_ready_observer.features[FeatureType.JOBS]
+        work_remaining[~is_ready.astype(bool)] = 0
+
+        return work_remaining.ravel()  # type: ignore[return-value]
+
+
+observer_based_most_work_remaining_rule = score_based_rule(
+    MostWorkRemainingScorer()
+)
 
 
 def most_operations_remaining_score(dispatcher: Dispatcher) -> list[int]:

job_shop_lib/dispatching/rules/_machine_chooser_factory.py

@@ -0,0 +1,69 @@
+"""Contains factory functions for creating dispatching rules, machine choosers,
+and pruning functions for the job shop scheduling problem.
+
+The factory functions create and return the appropriate functions based on the
+specified names or enums.
+"""
+
+from enum import Enum
+from collections.abc import Callable
+import random
+
+from job_shop_lib import Operation
+from job_shop_lib.exceptions import ValidationError
+from job_shop_lib.dispatching import Dispatcher
+
+
+class MachineChooserType(str, Enum):
+    """Enumeration of machine chooser strategies for the job shop scheduling"""
+
+    FIRST = "first"
+    RANDOM = "random"
+
+
+MachineChooser = Callable[[Dispatcher, Operation], int]
+
+
+def machine_chooser_factory(
+    machine_chooser: str | MachineChooser,
+) -> MachineChooser:
+    """Creates and returns a machine chooser function based on the specified
+    machine chooser strategy name.
+
+    The machine chooser function determines which machine an operation should
+    be assigned to for execution. The selection can be based on different
+    strategies such as choosing the first available machine or selecting a
+    machine randomly.
+
+    Args:
+        machine_chooser (str): The name of the machine chooser strategy to be
+            used. Supported values are 'first' and 'random'.
+
+    Returns:
+        A function that takes a :class:`~job_shop_lib.dispatching.Dispatcher`
+        and an :class:`~job_shop_lib.Operation` as input
+        and returns the index of the selected machine based on the specified
+        machine chooser strategy.
+
+    Raises:
+        ValueError: If the machine_chooser argument is not recognized or is
+            not supported.
+    """
+    machine_choosers: dict[str, Callable[[Dispatcher, Operation], int]] = {
+        MachineChooserType.FIRST: lambda _, operation: operation.machines[0],
+        MachineChooserType.RANDOM: lambda _, operation: random.choice(
+            operation.machines
+        ),
+    }
+
+    if callable(machine_chooser):
+        return machine_chooser
+
+    machine_chooser = machine_chooser.lower()
+    if machine_chooser not in machine_choosers:
+        raise ValidationError(
+            f"Machine chooser {machine_chooser} not recognized. Available "
+            f"machine choosers: {', '.join(machine_choosers)}."
+        )
+
+    return machine_choosers[machine_chooser]

job_shop_lib/dispatching/rules/_utils.py

@@ -0,0 +1,127 @@
+"""Utility functions."""
+
+import time
+from collections.abc import Callable
+import pandas as pd
+from job_shop_lib import JobShopInstance, Operation
+from job_shop_lib.exceptions import JobShopLibError
+from job_shop_lib.dispatching.rules import DispatchingRuleSolver
+from job_shop_lib.dispatching import Dispatcher
+
+
+def benchmark_dispatching_rules(
+    dispatching_rules: (
+        list[str | Callable[[Dispatcher], Operation]]
+        | list[str]
+        | list[Callable[[Dispatcher], Operation]]
+    ),
+    instances: list[JobShopInstance],
+) -> pd.DataFrame:
+    """Benchmark multiple dispatching rules on multiple JobShopInstances.
+
+    This function applies each provided dispatching rule to each given
+    :class:`JobShopInstance`, measuring the time taken to solve and the
+    makespan of the resulting schedule. It returns a DataFrame summarizing
+    the results.
+
+    Args:
+        dispatching_rules:
+            List of dispatching rules. Each rule can be
+            either a string (name of a built-in rule) or a callable
+            (custom rule function).
+        instances:
+             iList of :class:`JobShopInstance` objects to be solved.
+
+    Returns:
+        A pandas DataFrame with columns:
+            - instance: Name of the :class:`JobShopInstance`.
+            - rule: Name of the dispatching rule used.
+            - time: Time taken to solve the instance (in seconds).
+            - makespan: Makespan of the resulting schedule.
+
+    Raises:
+        Any exception that might occur during the solving process is caught
+        and logged, with None values recorded for time and makespan.
+
+    Example:
+        >>> from job_shop_lib.benchmarking import load_benchmark_instance
+        >>> instances = [load_benchmark_instance(f"ta{i:02d}")
+        ... for i in range(1, 3)]
+        >>> rules = ["most_work_remaining", "shortest_processing_time"]
+        >>> df = benchmark_dispatching_rules(rules, instances)
+        >>> print(df)
+          instance                        rule      time  makespan
+        0     ta01    shortest_processing_time  0.006492      3439
+        1     ta01    most_work_remaining_rule  0.012608      1583
+        2     ta02    shortest_processing_time  0.006240      2568
+        3     ta02    most_work_remaining_rule  0.012315      1630
+
+    Note:
+        - The function handles errors gracefully, allowing the benchmarking
+          process to continue even if solving a particular instance fails.
+        - For custom rule functions, the function name is used in the
+          'rule' column of the output DataFrame.
+    """
+    results = []
+
+    for instance in instances:
+        for rule in dispatching_rules:
+            solver = DispatchingRuleSolver(dispatching_rule=rule)
+
+            start_time = time.perf_counter()
+            try:
+                schedule = solver.solve(instance)
+                solve_time = time.perf_counter() - start_time
+                makespan = schedule.makespan()
+
+                results.append(
+                    {
+                        "instance": instance.name,
+                        "rule": (
+                            rule if isinstance(rule, str) else rule.__name__
+                        ),
+                        "time": solve_time,
+                        "makespan": makespan,
+                    }
+                )
+            except JobShopLibError as e:
+                print(f"Error solving {instance.name} with {rule}: {str(e)}")
+                results.append(
+                    {
+                        "instance": instance.name,
+                        "rule": (
+                            rule if isinstance(rule, str) else rule.__name__
+                        ),
+                        "time": None,
+                        "makespan": None,
+                    }
+                )
+
+    return pd.DataFrame(results)
+
+
+# Example usage:
+if __name__ == "__main__":
+    from job_shop_lib.benchmarking import load_benchmark_instance
+    from job_shop_lib.dispatching.rules._dispatching_rules_functions import (
+        most_work_remaining_rule,
+    )
+
+    # Load instances
+    instances_ = [load_benchmark_instance(f"ta{i:02d}") for i in range(1, 3)]
+
+    # Define rules
+    rules_: list[str | Callable[[Dispatcher], Operation]] = [
+        "most_work_remaining",
+        "shortest_processing_time",
+        most_work_remaining_rule,
+    ]
+
+    # Run benchmark
+    df = benchmark_dispatching_rules(rules_, instances_)
+
+    # Display results
+    print(df)
+
+    # Group results by rule and compute average makespan and time
+    print(df.groupby("rule")[["time", "makespan"]].mean())

job_shop_lib/exceptions.py

@@ -24,3 +24,21 @@ class NoSolutionFoundError(JobShopLibError):
     TypeError, which may indicate a bug in the code or an invalid
     input, rather than a failure to find a solution.
     """
+
+
+class ValidationError(JobShopLibError):
+    """Exception raised when a validation check fails.
+
+    This exception is raised when a validation check fails, indicating
+    that the input data is invalid or does not meet the requirements of
+    the function or class that is performing the validation.
+
+    It is useful to distinguish this exception from other exceptions
+    that may be raised by a function or class, such as a ValueError or
+    a TypeError, which may indicate a bug in the code or an invalid
+    input, rather than a validation failure.
+    """
+
+
+class UninitializedAttributeError(JobShopLibError):
+    """Exception raised when an attribute is accessed before initialization."""

job_shop_lib/generation/__init__.py

@@ -1,7 +1,7 @@
 """Package for generating job shop instances."""
 
-from job_shop_lib.generation.instance_generator import InstanceGenerator
-from job_shop_lib.generation.general_instance_generator import (
+from job_shop_lib.generation._instance_generator import InstanceGenerator
+from job_shop_lib.generation._general_instance_generator import (
     GeneralInstanceGenerator,
 )
 

job_shop_lib/generation/{general_instance_generator.py → _general_instance_generator.py}

@@ -3,6 +3,7 @@
 import random
 
 from job_shop_lib import JobShopInstance, Operation
+from job_shop_lib.exceptions import ValidationError
 from job_shop_lib.generation import InstanceGenerator
 
 
@@ -105,14 +106,32 @@ class GeneralInstanceGenerator(InstanceGenerator):
         if seed is not None:
             random.seed(seed)
 
-    def generate(self) -> JobShopInstance:
-        """Generates a single job shop instance"""
-        num_jobs = random.randint(*self.num_jobs_range)
+    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})"
+        )
 
-        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)
+    def generate(
+        self, num_jobs: int | None = None, num_machines: int | None = 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(
+                "Theere are fewer jobs than machines, which is not allowed"
+                "when `allow_less_jobs_than_machines` attribute is False."
+            )
 
         jobs = []
         available_machines = list(range(num_machines))

job_shop_lib/generation/{instance_generator.py → _instance_generator.py}

@@ -4,6 +4,7 @@ import random
 from typing import Iterator
 
 from job_shop_lib import JobShopInstance
+from job_shop_lib.exceptions import UninitializedAttributeError
 
 
 class InstanceGenerator(abc.ABC):
@@ -76,8 +77,17 @@ class InstanceGenerator(abc.ABC):
         self._iteration_limit = iteration_limit
 
     @abc.abstractmethod
-    def generate(self) -> JobShopInstance:
-        """Generates a single job shop instance"""
+    def generate(
+        self, num_jobs: int | None = None, num_machines: int | None = 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
@@ -98,7 +108,7 @@ class InstanceGenerator(abc.ABC):
 
     def __len__(self) -> int:
         if self._iteration_limit is None:
-            raise ValueError("Iteration limit is not set.")
+            raise UninitializedAttributeError("Iteration limit is not set.")
         return self._iteration_limit
 
     @property

job_shop_lib/graphs/__init__.py

@@ -1,16 +1,27 @@
-"""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 (
+.. autosummary::
+    JobShopGraph
+    Node
+    NodeType
+    build_disjunctive_graph
+    build_agent_task_graph
+    build_complete_agent_task_graph
+    build_agent_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,
     add_disjunctive_edges,
     add_conjunctive_edges,
     add_source_sink_nodes,
     add_source_sink_edges,
 )
-from job_shop_lib.graphs.build_agent_task_graph import (
+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,

job_shop_lib/graphs/{job_shop_graph.py → _job_shop_graph.py}

@@ -3,7 +3,8 @@
 import collections
 import networkx as nx
 
-from job_shop_lib import JobShopInstance, JobShopLibError
+from job_shop_lib import JobShopInstance
+from job_shop_lib.exceptions import ValidationError
 from job_shop_lib.graphs import Node, NodeType
 
 
@@ -168,7 +169,7 @@ class JobShopGraph:
         if isinstance(v_of_edge, Node):
             v_of_edge = v_of_edge.node_id
         if u_of_edge not in self.graph or v_of_edge not in self.graph:
-            raise JobShopLibError(
+            raise ValidationError(
                 "`u_of_edge` and `v_of_edge` must be in the graph."
             )
         self.graph.add_edge(u_of_edge, v_of_edge, **attr)
@@ -200,3 +201,81 @@ class JobShopGraph:
         if isinstance(node, Node):
             node = node.node_id
         return self.removed_nodes[node]
+
+    def non_removed_nodes(self) -> list[Node]:
+        """Returns the nodes that are not removed from the graph."""
+        return [node for node in self._nodes if not self.is_removed(node)]
+
+    def get_machine_node(self, machine_id: int) -> Node:
+        """Returns the node representing the machine with the given id.
+
+        Args:
+            machine_id: The id of the machine.
+
+        Returns:
+            The node representing the machine with the given id.
+        """
+        return self.get_node_by_type_and_id(
+            NodeType.MACHINE, machine_id, "machine_id"
+        )
+
+    def get_job_node(self, job_id: int) -> Node:
+        """Returns the node representing the job with the given id.
+
+        Args:
+            job_id: The id of the job.
+
+        Returns:
+            The node representing the job with the given id.
+        """
+        return self.get_node_by_type_and_id(NodeType.JOB, job_id, "job_id")
+
+    def get_operation_node(self, operation_id: int) -> Node:
+        """Returns the node representing the operation with the given id.
+
+        Args:
+            operation_id: The id of the operation.
+
+        Returns:
+            The node representing the operation with the given id.
+        """
+        return self.get_node_by_type_and_id(
+            NodeType.OPERATION, operation_id, "operation.operation_id"
+        )
+
+    def get_node_by_type_and_id(
+        self, node_type: NodeType, node_id: int, id_attr: str
+    ) -> Node:
+        """Generic method to get a node by type and id.
+
+        Args:
+            node_type:
+                The type of the node.
+            node_id:
+                The id of the node.
+            id_attr:
+                The attribute name to compare the id. Can be nested like
+                'operation.operation_id'.
+
+        Returns:
+            The node with the given id.
+        """
+
+        def get_nested_attr(obj, attr_path: str):
+            """Helper function to get nested attribute."""
+            attrs = attr_path.split(".")
+            for attr in attrs:
+                obj = getattr(obj, attr)
+            return obj
+
+        nodes = self._nodes_by_type[node_type]
+        if node_id < len(nodes):
+            node = nodes[node_id]
+            if get_nested_attr(node, id_attr) == node_id:
+                return node
+
+        for node in nodes:
+            if get_nested_attr(node, id_attr) == node_id:
+                return node
+
+        raise ValidationError(f"No node found with node.{id_attr}={node_id}")