job-shop-lib 1.0.0b5__py3-none-any.whl → 1.0.2__py3-none-any.whl

job_shop_lib/__init__.py

@@ -19,7 +19,7 @@ from job_shop_lib._schedule import Schedule
 from job_shop_lib._base_solver import BaseSolver, Solver
 
 
-__version__ = "1.0.0-b.5"
+__version__ = "1.0.2"
 
 __all__ = [
     "Operation",

job_shop_lib/_job_shop_instance.py

@@ -16,8 +16,8 @@ class JobShopInstance:
     """Data structure to store a Job Shop Scheduling Problem instance.
 
     Additional attributes such as ``num_machines`` or ``durations_matrix`` can
-    be computed from the instance and are cached for performance if they
-    require expensive computations.
+    be computed from the instance and are cached for performance since they
+    might require expensive computations.
 
     Methods:
 

job_shop_lib/_operation.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from typing import Union, List
 
-from job_shop_lib.exceptions import UninitializedAttributeError
+from job_shop_lib.exceptions import ValidationError
 
 
 class Operation:
@@ -81,8 +81,14 @@ class Operation:
                 If the operation has multiple machines in its list.
         """
         if len(self.machines) > 1:
-            raise UninitializedAttributeError(
-                "Operation has multiple machines."
+            raise ValidationError(
+                "Operation has multiple machines. The `machine_id` property "
+                "should only be used when working with a classic JSSP "
+                "instance. This error prevents silent bugs. To handle "
+                "operations with more machines you have to use the machines "
+                "attribute. If you get this error using `job_shop_lib` "
+                "objects, it means that that object does not support "
+                "operations with multiple machines yet."
             )
         return self.machines[0]
 

job_shop_lib/_scheduled_operation.py

@@ -80,3 +80,6 @@ class ScheduledOperation:
             and self.start_time == value.start_time
             and self.machine_id == value.machine_id
         )
+
+    def __hash__(self) -> int:
+        return hash((self.operation, self.start_time, self.machine_id))

job_shop_lib/benchmarking/__init__.py

@@ -1,6 +1,7 @@
 """Contains functions to load benchmark instances.
 
 .. autosummary::
+    :nosignatures:
 
     load_all_benchmark_instances
     load_benchmark_instance

job_shop_lib/dispatching/__init__.py

@@ -9,13 +9,15 @@ Problem step-by-step.
     HistoryObserver
     UnscheduledOperationsObserver
     OptimalOperationsObserver
-    ReadyOperationsFilter
     DispatcherObserverConfig
+    ReadyOperationsFilter
+    ReadyOperationsFilterType
+    ready_operations_filter_factory
     filter_dominated_operations
     filter_non_immediate_machines
+    filter_non_idle_machines
+    filter_non_immediate_operations
     create_composite_operation_filter
-    ReadyOperationsFilterType
-    ready_operations_filter_factory
 
 Dispatching refers to the decision-making process of selecting which job
 should be processed next on a particular machine when that machine becomes
@@ -45,17 +47,17 @@ from ._factories import (
 
 __all__ = [
     "Dispatcher",
-    "filter_dominated_operations",
-    "filter_non_immediate_machines",
-    "create_composite_operation_filter",
-    "ReadyOperationsFilterType",
-    "ready_operations_filter_factory",
     "DispatcherObserver",
     "HistoryObserver",
-    "DispatcherObserverConfig",
     "UnscheduledOperationsObserver",
+    "OptimalOperationsObserver",
+    "DispatcherObserverConfig",
     "ReadyOperationsFilter",
+    "ReadyOperationsFilterType",
+    "ready_operations_filter_factory",
+    "filter_dominated_operations",
+    "filter_non_immediate_machines",
     "filter_non_idle_machines",
     "filter_non_immediate_operations",
-    "OptimalOperationsObserver",
+    "create_composite_operation_filter",
 ]

job_shop_lib/dispatching/_dispatcher.py

@@ -336,8 +336,7 @@ class Dispatcher:
                 The operation to be scheduled.
             machine_id:
                 The id of the machine on which the operation is to be
-                scheduled. If ``None``, the start time is computed based on the
-                next available time for the operation on any machine.
+                scheduled.
         """
         return max(
             self._machine_next_available_time[machine_id],
@@ -459,12 +458,11 @@ class Dispatcher:
         return unscheduled_operations
 
     @_dispatcher_cache
-    def scheduled_operations(self) -> List[Operation]:
+    def scheduled_operations(self) -> List[ScheduledOperation]:
         """Returns the list of operations that have been scheduled."""
         scheduled_operations = []
-        for job_id, next_position in enumerate(self._job_next_operation_index):
-            operations = self.instance.jobs[job_id][:next_position]
-            scheduled_operations.extend(operations)
+        for machine_schedule in self.schedule.schedule:
+            scheduled_operations.extend(machine_schedule)
         return scheduled_operations
 
     @_dispatcher_cache
@@ -532,19 +530,14 @@ class Dispatcher:
         return scheduled_operation.end_time - adjusted_start_time
 
     @_dispatcher_cache
-    def completed_operations(self) -> Set[Operation]:
+    def completed_operations(self) -> Set[ScheduledOperation]:
         """Returns the set of operations that have been completed.
 
         This method returns the operations that have been scheduled and the
         current time is greater than or equal to the end time of the operation.
         """
         scheduled_operations = set(self.scheduled_operations())
-        ongoing_operations = set(
-            map(
-                lambda scheduled_op: scheduled_op.operation,
-                self.ongoing_operations(),
-            )
-        )
+        ongoing_operations = set(self.ongoing_operations())
         completed_operations = scheduled_operations - ongoing_operations
         return completed_operations
 

job_shop_lib/dispatching/_factories.py

@@ -95,9 +95,9 @@ def ready_operations_filter_factory(
 
     Args:
         filter_name:
-            The name of the filter function to be used. Supported
-            values are 'dominated_operations' and
-            'immediate_machine_operations'.
+            The name of the filter function to be used. See
+            :class:`ReadyOperationsFilterType` for supported values.
+            Alternatively, a custom filter function can be passed directly.
 
     Returns:
         A function that takes a :class:`~job_shop_lib.dispatching.Dispatcher`

job_shop_lib/dispatching/_optimal_operations_observer.py

@@ -20,8 +20,6 @@ class OptimalOperationsObserver(DispatcherObserver):
             based on the reference schedule.
         reference_schedule: The reference schedule used to determine optimal
             operations.
-        _operation_to_scheduled: Dictionary mapping operations to their
-            scheduled versions in the reference schedule.
 
     Args:
         dispatcher: The dispatcher instance to observe.

job_shop_lib/dispatching/_ready_operation_filters.py

@@ -153,16 +153,16 @@ def _get_min_machine_end_times(
 
 
 def _get_immediate_machines(
-    self: Dispatcher, available_operations: List[Operation]
+    dispatcher: Dispatcher, available_operations: List[Operation]
 ) -> List[bool]:
     """Returns the machine ids of the machines that have at least one
     operation with the lowest start time (i.e. the start time)."""
-    working_machines = [False] * self.instance.num_machines
+    working_machines = [False] * dispatcher.instance.num_machines
     # We can't use the current_time directly because it will cause
     # an infinite loop.
-    current_time = self.min_start_time(available_operations)
+    current_time = dispatcher.min_start_time(available_operations)
     for op in available_operations:
         for machine_id in op.machines:
-            if self.start_time(op, machine_id) == current_time:
+            if dispatcher.start_time(op, machine_id) == current_time:
                 working_machines[machine_id] = True
     return working_machines

job_shop_lib/dispatching/feature_observers/_composite_feature_observer.py

@@ -2,10 +2,10 @@
 
 from collections import defaultdict
 from collections.abc import Sequence
-from typing import List, Dict, Union, Optional
+from typing import List, Dict, Union, Optional, Type
 # The Self type can be imported directly from Python’s typing module in
 # version 3.11 and beyond. We use the typing_extensions module to support
-# python >=3.8
+# python >=3.10
 from typing_extensions import Self
 import numpy as np
 from numpy.typing import NDArray
@@ -18,6 +18,7 @@ from job_shop_lib.dispatching.feature_observers import (
     FeatureType,
     FeatureObserverConfig,
     feature_observer_factory,
+    FeatureObserverType,
 )
 
 
@@ -104,7 +105,14 @@ class CompositeFeatureObserver(FeatureObserver):
     def from_feature_observer_configs(
         cls,
         dispatcher: Dispatcher,
-        feature_observer_configs: Sequence[FeatureObserverConfig],
+        feature_observer_configs: Sequence[
+            Union[
+                str,
+                FeatureObserverType,
+                Type[FeatureObserver],
+                FeatureObserverConfig,
+            ],
+        ],
         subscribe: bool = True,
     ) -> Self:
         """Creates the composite feature observer.
@@ -178,9 +186,6 @@ if __name__ == "__main__":
     import time
     from job_shop_lib.benchmarking import load_benchmark_instance
     from job_shop_lib.dispatching.rules import DispatchingRuleSolver
-    from job_shop_lib.dispatching.feature_observers import (
-        FeatureObserverType,
-    )
 
     ta80 = load_benchmark_instance("ta80")
 

job_shop_lib/dispatching/feature_observers/_factory.py

@@ -39,9 +39,14 @@ class FeatureObserverType(str, Enum):
 # FeatureObserverConfig = DispatcherObserverConfig[
 #     Type[FeatureObserver] | FeatureObserverType | str
 # ]
-FeatureObserverConfig = DispatcherObserverConfig[
-    Union[Type[FeatureObserver], FeatureObserverType, str]
-]
+# FeatureObserverConfig = DispatcherObserverConfig[
+#     Union[Type[FeatureObserver], FeatureObserverType, str]
+# ]
+FeatureObserverConfig = (
+    DispatcherObserverConfig[Type[FeatureObserver]]
+    | DispatcherObserverConfig[FeatureObserverType]
+    | DispatcherObserverConfig[str]
+)
 
 
 def feature_observer_factory(

job_shop_lib/dispatching/feature_observers/_feature_observer.py

@@ -36,7 +36,7 @@ class FeatureObserver(DispatcherObserver):
     individually. Furthermore, machine learning models can be trained on these
     arrays to predict the best dispatching decisions.
 
-    Arrays use the data type ``np.float32``. This is because most machine
+    Arrays use the data type ``np.float32``.
 
     New :class:`FeatureObservers` must inherit from this class, and re-define
     the class attributes ``_singleton`` (defualt ), ``_feature_size``

job_shop_lib/dispatching/feature_observers/_is_completed_observer.py

@@ -4,14 +4,10 @@ from typing import Optional, Union, List
 import numpy as np
 
 from job_shop_lib import ScheduledOperation
-from job_shop_lib.dispatching import (
-    Dispatcher,
-    DispatcherObserver,
-)
+from job_shop_lib.dispatching import Dispatcher
 from job_shop_lib.dispatching.feature_observers import (
     FeatureObserver,
     FeatureType,
-    RemainingOperationsObserver,
 )
 
 
@@ -40,15 +36,6 @@ class IsCompletedObserver(FeatureObserver):
             or manually updated.
     """
 
-    __slots__ = {
-        "remaining_ops_per_machine": (
-            "The number of unscheduled operations per machine."
-        ),
-        "remaining_ops_per_job": (
-            "The number of unscheduled operations per job."
-        ),
-    }
-
     def __init__(
         self,
         dispatcher: Dispatcher,
@@ -57,11 +44,16 @@ class IsCompletedObserver(FeatureObserver):
         subscribe: bool = True,
     ):
         feature_types = self._get_feature_types_list(feature_types)
-        self.remaining_ops_per_machine = np.zeros(
-            (dispatcher.instance.num_machines, 1), dtype=int
+        self._num_of_operations_per_machine = np.array(
+            [
+                len(operations_by_machine)
+                for operations_by_machine in (
+                    dispatcher.instance.operations_by_machine
+                )
+            ]
         )
-        self.remaining_ops_per_job = np.zeros(
-            (dispatcher.instance.num_jobs, 1), dtype=int
+        self._num_of_operations_per_job = np.array(
+            [len(job) for job in dispatcher.instance.jobs]
         )
         super().__init__(
             dispatcher,
@@ -70,60 +62,36 @@ class IsCompletedObserver(FeatureObserver):
         )
 
     def initialize_features(self):
-        def _has_same_features(observer: DispatcherObserver) -> bool:
-            if not isinstance(observer, RemainingOperationsObserver):
-                return False
-            return all(
-                feature_type in observer.features
-                for feature_type in remaining_ops_feature_types
-            )
-
-        self.set_features_to_zero()
-
-        remaining_ops_feature_types = [
-            feature_type
-            for feature_type in self.features.keys()
-            if feature_type != FeatureType.OPERATIONS
-        ]
-        remaining_ops_observer = self.dispatcher.create_or_get_observer(
-            RemainingOperationsObserver,
-            condition=_has_same_features,
-            feature_types=remaining_ops_feature_types,
-        )
-        if FeatureType.JOBS in self.features:
-            self.remaining_ops_per_job = remaining_ops_observer.features[
-                FeatureType.JOBS
-            ].copy()
-        if FeatureType.MACHINES in self.features:
-            self.remaining_ops_per_machine = remaining_ops_observer.features[
-                FeatureType.MACHINES
-            ].copy()
-
-    def reset(self):
-        self.initialize_features()
-
-    def update(self, scheduled_operation: ScheduledOperation):
         if FeatureType.OPERATIONS in self.features:
             completed_operations = [
-                op.operation_id
+                op.operation.operation_id
                 for op in self.dispatcher.completed_operations()
             ]
             self.features[FeatureType.OPERATIONS][completed_operations, 0] = 1
         if FeatureType.MACHINES in self.features:
-            self.remaining_ops_per_machine[
-                scheduled_operation.operation.machines, 0
-            ] -= 1
-            is_completed = (
-                self.remaining_ops_per_machine[
-                    scheduled_operation.operation.machines, 0
-                ]
-                == 0
+            num_completed_ops_per_machine = np.zeros(
+                len(self._num_of_operations_per_machine)
             )
-            self.features[FeatureType.MACHINES][
-                scheduled_operation.operation.machines, 0
-            ] = is_completed
+            for op in self.dispatcher.completed_operations():
+                for machine_id in op.operation.machines:
+                    num_completed_ops_per_machine[machine_id] += 1
+            self.features[FeatureType.MACHINES][:, 0] = (
+                num_completed_ops_per_machine
+                == self._num_of_operations_per_machine
+            ).astype(np.float32)
         if FeatureType.JOBS in self.features:
-            job_id = scheduled_operation.job_id
-            self.remaining_ops_per_job[job_id, 0] -= 1
-            is_completed = self.remaining_ops_per_job[job_id, 0] == 0
-            self.features[FeatureType.JOBS][job_id, 0] = is_completed
+            num_completed_ops_per_job = np.zeros(
+                len(self._num_of_operations_per_job)
+            )
+            for op in self.dispatcher.completed_operations():
+                num_completed_ops_per_job[op.operation.job_id] += 1
+            self.features[FeatureType.JOBS][:, 0] = (
+                num_completed_ops_per_job
+                == self._num_of_operations_per_job
+            ).astype(np.float32)
+
+    def reset(self):
+        self.set_features_to_zero()
+
+    def update(self, scheduled_operation: ScheduledOperation):
+        self.initialize_features()

job_shop_lib/dispatching/rules/__init__.py

@@ -3,17 +3,19 @@
 Main objects:
 
 .. autosummary::
+    :nosignatures:
 
     DispatchingRuleSolver
-    dispatching_rule_factory
     DispatchingRuleType
-    MachineChooserType
     dispatching_rule_factory
+    MachineChooserType
     machine_chooser_factory
+    MachineChooser
 
 Dispatching rules:
 
 .. autosummary::
+    :nosignatures:
 
     shortest_processing_time_rule
     first_come_first_served_rule
@@ -27,6 +29,7 @@ Dispatching rules:
 Dispatching rule scorers:
 
 .. autosummary::
+    :nosignatures:
 
     shortest_processing_time_score
     first_come_first_served_score
@@ -65,6 +68,11 @@ from ._dispatching_rule_solver import DispatchingRuleSolver
 
 
 __all__ = [
+    "DispatchingRuleSolver",
+    "DispatchingRuleType",
+    "dispatching_rule_factory",
+    "MachineChooserType",
+    "machine_chooser_factory",
     "shortest_processing_time_rule",
     "first_come_first_served_rule",
     "most_work_remaining_rule",
@@ -72,16 +80,11 @@ __all__ = [
     "random_operation_rule",
     "score_based_rule",
     "score_based_rule_with_tie_breaker",
+    "observer_based_most_work_remaining_rule",
     "shortest_processing_time_score",
     "first_come_first_served_score",
     "MostWorkRemainingScorer",
     "most_operations_remaining_score",
     "random_score",
-    "dispatching_rule_factory",
-    "DispatchingRuleType",
-    "MachineChooserType",
-    "machine_chooser_factory",
     "MachineChooser",
-    "DispatchingRuleSolver",
-    "observer_based_most_work_remaining_rule",
 ]

job_shop_lib/dispatching/rules/_dispatching_rule_factory.py

@@ -33,7 +33,7 @@ class DispatchingRuleType(str, Enum):
 
 
 def dispatching_rule_factory(
-    dispatching_rule: Union[str, DispatchingRuleType,]
+    dispatching_rule: Union[str, DispatchingRuleType],
 ) -> Callable[[Dispatcher], Operation]:
     """Creates and returns a dispatching rule function based on the specified
     dispatching rule name.

job_shop_lib/dispatching/rules/_machine_chooser_factory.py

@@ -47,8 +47,9 @@ def machine_chooser_factory(
         machine chooser strategy.
 
     Raises:
-        ValueError: If the machine_chooser argument is not recognized or is
-            not supported.
+        ValidationError:
+            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],

job_shop_lib/generation/__init__.py

@@ -1,4 +1,15 @@
-"""Package for generating job shop instances."""
+"""Package for generating job shop instances.
+
+.. autosummary::
+    :nosignatures:
+
+    InstanceGenerator
+    GeneralInstanceGenerator
+    generate_duration_matrix
+    generate_machine_matrix_with_recirculation
+    generate_machine_matrix_without_recirculation
+
+"""
 
 from job_shop_lib.generation._utils import (
     generate_duration_matrix,

job_shop_lib/graphs/__init__.py

@@ -2,15 +2,47 @@
 
 The main classes and functions available in this package are:
 
+Main objects:
+
 .. autosummary::
+    :nosignatures:
+
     JobShopGraph
     Node
     NodeType
+    EdgeType
+    NODE_ATTR
+
+Build functions:
+
+.. autosummary::
+    :nosignatures:
+
     build_disjunctive_graph
-    build_solved_disjunctive_graph
     build_resource_task_graph
     build_complete_resource_task_graph
     build_resource_task_graph_with_jobs
+    build_solved_disjunctive_graph
+
+Add functions:
+
+.. autosummary::
+    :nosignatures:
+
+    add_disjunctive_edges
+    add_conjunctive_edges
+    add_source_sink_nodes
+    add_source_sink_edges
+    add_same_job_operations_edges
+    add_machine_nodes
+    add_operation_machine_edges
+    add_machine_machine_edges
+    add_job_nodes
+    add_operation_job_edges
+    add_global_node
+    add_machine_global_edges
+    add_job_global_edges
+    add_job_job_edges
 
 """
 
@@ -38,23 +70,25 @@ from job_shop_lib.graphs._build_resource_task_graphs import (
     add_global_node,
     add_machine_global_edges,
     add_job_global_edges,
+    add_job_job_edges,
 )
 
 
 __all__ = [
-    "EdgeType",
-    "NodeType",
-    "Node",
     "JobShopGraph",
+    "Node",
+    "NodeType",
+    "EdgeType",
     "NODE_ATTR",
     "build_disjunctive_graph",
+    "build_resource_task_graph",
+    "build_complete_resource_task_graph",
+    "build_resource_task_graph_with_jobs",
+    "build_solved_disjunctive_graph",
     "add_disjunctive_edges",
     "add_conjunctive_edges",
     "add_source_sink_nodes",
     "add_source_sink_edges",
-    "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",
@@ -64,5 +98,5 @@ __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_resource_task_graphs.py

@@ -1,7 +1,7 @@
 """Contains helper functions to build the resource-task graphs from a job shop
 instance.
 
-The agent-task graph (renamed to resource-task graph) was introduced by
+The resource-task graph (originally called agent-task graph) was introduced by
 Junyoung Park et al. (2021).
 In contrast to the disjunctive graph, instead of connecting operations that
 share the same resources directly by disjunctive edges, operation nodes are