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

job_shop_lib/dispatching/_ready_operation_filters.py

@@ -15,6 +15,86 @@ ReadyOperationsFilter = Callable[
 ]
 
 
+def filter_non_idle_machines(
+    dispatcher: Dispatcher, operations: list[Operation]
+) -> list[Operation]:
+    """Filters out all the operations associated with non-idle machines.
+
+    A machine is considered idle if there are no ongoing operations
+    currently scheduled on it. This filter removes operations that are
+    associated with machines that are busy (i.e., have at least one
+    uncompleted operation).
+
+    Utilizes :meth:``Dispatcher.ongoing_operations()`` to determine machine
+    statuses.
+
+    Args:
+        dispatcher: The dispatcher object.
+        operations: The list of operations to filter.
+
+    Returns:
+        The list of operations that are associated with idle machines.
+    """
+    current_time = dispatcher.min_start_time(operations)
+    non_idle_machines = _get_non_idle_machines(dispatcher, current_time)
+
+    # Filter operations to keep those that are associated with at least one
+    # idle machine
+    filtered_operations: list[Operation] = []
+    for operation in operations:
+        if all(
+            machine_id in non_idle_machines
+            for machine_id in operation.machines
+        ):
+            continue
+        filtered_operations.append(operation)
+
+    return filtered_operations
+
+
+def _get_non_idle_machines(
+    dispatcher: Dispatcher, current_time: int
+) -> set[int]:
+    """Returns the set of machine ids that are currently busy (i.e., have at
+    least one uncompleted operation)."""
+
+    non_idle_machines = set()
+    for machine_schedule in dispatcher.schedule.schedule:
+        for scheduled_operation in reversed(machine_schedule):
+            is_completed = scheduled_operation.end_time <= current_time
+            if is_completed:
+                break
+            non_idle_machines.add(scheduled_operation.machine_id)
+
+    return non_idle_machines
+
+
+def filter_non_immediate_operations(
+    dispatcher: Dispatcher, operations: list[Operation]
+) -> list[Operation]:
+    """Filters out all the operations that can't start immediately.
+
+    An operation can start immediately if its earliest start time is the
+    current time.
+
+    The current time is determined by the minimum start time of the
+    operations.
+
+    Args:
+        dispatcher: The dispatcher object.
+        operations: The list of operations to filter.
+    """
+
+    min_start_time = dispatcher.min_start_time(operations)
+    immediate_operations: list[Operation] = []
+    for operation in operations:
+        start_time = dispatcher.earliest_start_time(operation)
+        if start_time == min_start_time:
+            immediate_operations.append(operation)
+
+    return immediate_operations
+
+
 def filter_dominated_operations(
     dispatcher: Dispatcher, operations: list[Operation]
 ) -> list[Operation]:

job_shop_lib/dispatching/feature_observers/_composite_feature_observer.py

@@ -193,7 +193,6 @@ if __name__ == "__main__":
             dispatcher=dispatcher_,
         )
         for observer_type in feature_observer_types_
-        if not observer_type == FeatureObserverType.COMPOSITE
         # and not FeatureObserverType.EARLIEST_START_TIME
     ]
     composite_observer_ = CompositeFeatureObserver(

job_shop_lib/dispatching/feature_observers/_factory.py

@@ -1,4 +1,4 @@
-"""Contains factory functions for creating node feature encoders."""
+"""Contains factory functions for creating :class:`FeatureObserver`s."""
 
 from enum import Enum
 
@@ -18,8 +18,12 @@ from job_shop_lib.dispatching.feature_observers import (
 class FeatureObserverType(str, Enum):
     """Enumeration of the different feature observers.
 
-    Each feature observer is associated with a string value that can be used
-    to create the feature observer using the factory function.
+    Each :class:`FeatureObserver` is associated with a string value that can be
+    used to create the :class:`FeatureObserver` using the factory function.
+
+    It does not include the :class:`CompositeFeatureObserver` class since this
+    observer is often managed separately from the others. For example, a
+    common use case is to create a list of feature observers and pass them to
     """
 
     IS_READY = "is_ready"
@@ -29,7 +33,6 @@ class FeatureObserverType(str, Enum):
     POSITION_IN_JOB = "position_in_job"
     REMAINING_OPERATIONS = "remaining_operations"
     IS_COMPLETED = "is_completed"
-    COMPOSITE = "composite"
 
 
 # FeatureObserverConfig = DispatcherObserverConfig[
@@ -43,7 +46,7 @@ FeatureObserverConfig = (
 
 
 def feature_observer_factory(
-    feature_creator_type: (
+    feature_observer_type: (
         str
         | FeatureObserverType
         | type[FeatureObserver]
@@ -51,29 +54,29 @@ def feature_observer_factory(
     ),
     **kwargs,
 ) -> FeatureObserver:
-    """Creates and returns a node feature creator based on the specified
-    node feature creator type.
+    """Creates and returns a :class:`FeatureObserver` based on the specified
+    :class:`FeatureObserver` type.
 
     Args:
         feature_creator_type:
-            The type of node feature creator to create.
+            The type of :class:`FeatureObserver` to create.
         **kwargs:
-            Additional keyword arguments to pass to the node
-            feature creator constructor.
+            Additional keyword arguments to pass to the
+            :class:`FeatureObserver` constructor.
 
     Returns:
-        A node feature creator instance.
+        A :class:`FeatureObserver` instance.
     """
-    if isinstance(feature_creator_type, DispatcherObserverConfig):
+    if isinstance(feature_observer_type, DispatcherObserverConfig):
         return feature_observer_factory(
-            feature_creator_type.class_type,
-            **feature_creator_type.kwargs,
+            feature_observer_type.class_type,
+            **feature_observer_type.kwargs,
             **kwargs,
         )
     # if the instance is of type type[FeatureObserver] we can just
     # call the object constructor with the keyword arguments
-    if isinstance(feature_creator_type, type):
-        return feature_creator_type(**kwargs)
+    if isinstance(feature_observer_type, type):
+        return feature_observer_type(**kwargs)
 
     mapping: dict[FeatureObserverType, type[FeatureObserver]] = {
         FeatureObserverType.IS_READY: IsReadyObserver,
@@ -84,5 +87,5 @@ def feature_observer_factory(
         FeatureObserverType.REMAINING_OPERATIONS: RemainingOperationsObserver,
         FeatureObserverType.IS_COMPLETED: IsCompletedObserver,
     }
-    feature_creator = mapping[feature_creator_type]  # type: ignore[index]
-    return feature_creator(**kwargs)
+    feature_observer = mapping[feature_observer_type]  # type: ignore[index]
+    return feature_observer(**kwargs)

job_shop_lib/dispatching/feature_observers/_is_completed_observer.py

@@ -51,6 +51,7 @@ class IsCompletedObserver(FeatureObserver):
     def __init__(
         self,
         dispatcher: Dispatcher,
+        *,
         feature_types: list[FeatureType] | FeatureType | None = None,
         subscribe: bool = True,
     ):

job_shop_lib/dispatching/feature_observers/_is_ready_observer.py

@@ -29,5 +29,5 @@ class IsReadyObserver(FeatureObserver):
         self.initialize_features()
 
     def _get_ready_operations(self) -> list[int]:
-        available_operations = self.dispatcher.ready_operations()
+        available_operations = self.dispatcher.available_operations()
         return [operation.operation_id for operation in available_operations]

job_shop_lib/dispatching/rules/_dispatching_rule_solver.py

@@ -1,12 +1,14 @@
 """Home of the `DispatchingRuleSolver` class."""
 
-from collections.abc import Callable
+from collections.abc import Callable, Iterable
 
 from job_shop_lib import JobShopInstance, Schedule, Operation, BaseSolver
 from job_shop_lib.dispatching import (
     ready_operations_filter_factory,
     Dispatcher,
     ReadyOperationsFilterType,
+    ReadyOperationsFilter,
+    create_composite_operation_filter,
 )
 from job_shop_lib.dispatching.rules import (
     dispatching_rule_factory,
@@ -30,6 +32,35 @@ class DispatchingRuleSolver(BaseSolver):
         pruning_function:
             The pruning function to use. It is used to initialize the
             dispatcher object internally when calling the solve method.
+
+    Args:
+        dispatching_rule:
+            The dispatching rule to use. It can be a string with the name
+            of the dispatching rule, a class`DispatchingRuleType` enum member,
+            or a callable that takes a dispatcher and returns the operation to
+            be dispatched next.
+        machine_chooser:
+            The machine chooser to use. It can be a string with the name
+            of the machine chooser, a :class:`MachineChooserType` member, or a
+            callable that takes a dispatcher and an operation and returns
+            the machine id where the operation will be dispatched.
+        ready_operations_filter:
+            The ready operations filter to use. It can be either:
+
+            - a string with the name of the pruning function
+            - a :class`ReadyOperationsFilterType` enum member.
+            - a callable that takes a dispatcher and a list of operations
+              and returns a list of operations that should be considered
+              for dispatching,
+            - a list with names or actual ready operations filters to be used.
+              If a list is provided, a composite filter will be created
+              using the specified filters.
+
+    .. seealso::
+        - :func:`job_shop_lib.dispatching.rules.dispatching_rule_factory`
+        - :func:`job_shop_lib.dispatching.rules.machine_chooser_factory`
+        - :func:`~job_shop_lib.dispatching.ready_operations_filter_factory`
+        - :func:`~job_shop_lib.dispatching.create_composite_operation_filter`
     """
 
     def __init__(
@@ -41,32 +72,16 @@ class DispatchingRuleSolver(BaseSolver):
             str | Callable[[Dispatcher, Operation], int]
         ) = MachineChooserType.FIRST,
         ready_operations_filter: (
-            str
-            | Callable[[Dispatcher, list[Operation]], list[Operation]]
+            Iterable[ReadyOperationsFilter | str | ReadyOperationsFilterType]
+            | str
+            | ReadyOperationsFilterType
+            | ReadyOperationsFilter
             | None
-        ) = ReadyOperationsFilterType.DOMINATED_OPERATIONS,
+        ) = (
+            ReadyOperationsFilterType.DOMINATED_OPERATIONS,
+            ReadyOperationsFilterType.NON_IDLE_MACHINES,
+        ),
     ):
-        """Initializes the solver with the given dispatching rule, machine
-        chooser and pruning function.
-
-        Args:
-            dispatching_rule:
-                The dispatching rule to use. It can be a string with the name
-                of the dispatching rule, a DispatchingRule enum member, or a
-                callable that takes a dispatcher and returns the operation to
-                be dispatched next.
-            machine_chooser:
-                The machine chooser to use. It can be a string with the name
-                of the machine chooser, a MachineChooser enum member, or a
-                callable that takes a dispatcher and an operation and returns
-                the machine id where the operation will be dispatched.
-            ready_operations_filter:
-                The ready operations filter to use. It can be a string with
-                the name of the pruning function, a PruningFunction enum
-                member, or a callable that takes a dispatcher and a list of
-                operations and returns a list of operations that should be
-                considered for dispatching.
-        """
         if isinstance(dispatching_rule, str):
             dispatching_rule = dispatching_rule_factory(dispatching_rule)
         if isinstance(machine_chooser, str):
@@ -75,6 +90,10 @@ class DispatchingRuleSolver(BaseSolver):
             ready_operations_filter = ready_operations_filter_factory(
                 ready_operations_filter
             )
+        if isinstance(ready_operations_filter, Iterable):
+            ready_operations_filter = create_composite_operation_filter(
+                ready_operations_filter
+            )
 
         self.dispatching_rule = dispatching_rule
         self.machine_chooser = machine_chooser

job_shop_lib/dispatching/rules/_dispatching_rules_functions.py

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

job_shop_lib/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."""