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

job_shop_lib/dispatching/feature_observers/factory.py

@@ -0,0 +1,58 @@
+"""Contains factory functions for creating node feature encoders."""
+
+from enum import Enum
+
+from job_shop_lib.dispatching.feature_observers import (
+    IsReadyObserver,
+    EarliestStartTimeObserver,
+    FeatureObserver,
+    DurationObserver,
+    IsScheduledObserver,
+    PositionInJobObserver,
+    RemainingOperationsObserver,
+    IsCompletedObserver,
+)
+
+
+class FeatureObserverType(str, Enum):
+    """Enumeration of node feature creator types for the job shop scheduling
+    problem."""
+
+    IS_READY = "is_ready"
+    EARLIEST_START_TIME = "earliest_start_time"
+    DURATION = "duration"
+    IS_SCHEDULED = "is_scheduled"
+    POSITION_IN_JOB = "position_in_job"
+    REMAINING_OPERATIONS = "remaining_operations"
+    IS_COMPLETED = "is_completed"
+    COMPOSITE = "composite"
+
+
+def feature_observer_factory(
+    node_feature_creator_type: str | FeatureObserverType,
+    **kwargs,
+) -> FeatureObserver:
+    """Creates and returns a node feature creator based on the specified
+    node feature creator type.
+
+    Args:
+        node_feature_creator_type:
+            The type of node feature creator to create.
+        **kwargs:
+            Additional keyword arguments to pass to the node
+            feature creator constructor.
+
+    Returns:
+        A node feature creator instance.
+    """
+    mapping: dict[FeatureObserverType, type[FeatureObserver]] = {
+        FeatureObserverType.IS_READY: IsReadyObserver,
+        FeatureObserverType.EARLIEST_START_TIME: EarliestStartTimeObserver,
+        FeatureObserverType.DURATION: DurationObserver,
+        FeatureObserverType.IS_SCHEDULED: IsScheduledObserver,
+        FeatureObserverType.POSITION_IN_JOB: PositionInJobObserver,
+        FeatureObserverType.REMAINING_OPERATIONS: RemainingOperationsObserver,
+        FeatureObserverType.IS_COMPLETED: IsCompletedObserver,
+    }
+    feature_creator = mapping[node_feature_creator_type]  # type: ignore[index]
+    return feature_creator(**kwargs)

job_shop_lib/dispatching/feature_observers/feature_observer.py

@@ -0,0 +1,113 @@
+"""Home of the `FeatureObserver` class and `FeatureType` enum."""
+
+import enum
+
+import numpy as np
+from job_shop_lib import ScheduledOperation
+from job_shop_lib.dispatching import Dispatcher, DispatcherObserver
+
+
+class FeatureType(str, enum.Enum):
+    """Types of features that can be extracted."""
+
+    OPERATIONS = "operations"
+    MACHINES = "machines"
+    JOBS = "jobs"
+
+
+class FeatureObserver(DispatcherObserver):
+    """Base class for feature observers."""
+
+    def __init__(
+        self,
+        dispatcher: Dispatcher,
+        feature_types: list[FeatureType] | FeatureType | None = None,
+        feature_size: dict[FeatureType, int] | int = 1,
+        is_singleton: bool = True,
+        subscribe: bool = True,
+    ):
+        feature_types = self.get_feature_types_list(feature_types)
+        if isinstance(feature_size, int):
+            feature_size = {
+                feature_type: feature_size for feature_type in feature_types
+            }
+        super().__init__(dispatcher, is_singleton, subscribe)
+
+        number_of_entities = {
+            FeatureType.OPERATIONS: dispatcher.instance.num_operations,
+            FeatureType.MACHINES: dispatcher.instance.num_machines,
+            FeatureType.JOBS: dispatcher.instance.num_jobs,
+        }
+        self.feature_dimensions = {
+            feature_type: (
+                number_of_entities[feature_type],
+                feature_size[feature_type],
+            )
+            for feature_type in feature_types
+        }
+        self.features = {
+            feature_type: np.zeros(
+                self.feature_dimensions[feature_type],
+                dtype=np.float32,
+            )
+            for feature_type in feature_types
+        }
+        self.initialize_features()
+
+    def initialize_features(self):
+        """Initializes the features based on the current state of the
+        dispatcher."""
+
+    def update(self, scheduled_operation: ScheduledOperation):
+        """Updates the features based on the scheduled operation.
+
+        By default, this method just calls `initialize_features`.
+
+        Args:
+            scheduled_operation:
+                The operation that has been scheduled.
+        """
+        self.initialize_features()
+
+    def reset(self):
+        """Sets features to zero and calls to `initialize_features`."""
+        self.set_features_to_zero()
+        self.initialize_features()
+
+    def set_features_to_zero(
+        self, exclude: FeatureType | list[FeatureType] | None = None
+    ):
+        """Sets features to zero."""
+        if exclude is None:
+            exclude = []
+        if isinstance(exclude, FeatureType):
+            exclude = [exclude]
+
+        for feature_type in self.features:
+            if feature_type in exclude:
+                continue
+            self.features[feature_type][:] = 0.0
+
+    @staticmethod
+    def get_feature_types_list(
+        feature_types: list[FeatureType] | FeatureType | None,
+    ) -> list[FeatureType]:
+        """Returns a list of feature types.
+
+        Args:
+            feature_types:
+                A list of feature types or a single feature type. If `None`,
+                all feature types are returned.
+        """
+        if isinstance(feature_types, FeatureType):
+            feature_types = [feature_types]
+        if feature_types is None:
+            feature_types = list(FeatureType)
+        return feature_types
+
+    def __str__(self):
+        out = [self.__class__.__name__, ":\n"]
+        out.append("-" * len(out[0]))
+        for feature_type, feature in self.features.items():
+            out.append(f"\n{feature_type.value}:\n{feature}")
+        return "".join(out)

job_shop_lib/dispatching/feature_observers/is_completed_observer.py

@@ -0,0 +1,98 @@
+"""Home of the `IsCompletedObserver` class."""
+
+from typing import Iterable
+
+import numpy as np
+
+from job_shop_lib import ScheduledOperation
+from job_shop_lib.dispatching import Dispatcher
+from job_shop_lib.dispatching.feature_observers import (
+    FeatureObserver,
+    FeatureType,
+    RemainingOperationsObserver,
+)
+
+
+class IsCompletedObserver(FeatureObserver):
+    """Observer that adds a binary feature indicating whether each operation,
+    machine, or job has been completed."""
+
+    def __init__(
+        self,
+        dispatcher: Dispatcher,
+        feature_types: list[FeatureType] | FeatureType | None = None,
+    ):
+        feature_types = self.get_feature_types_list(feature_types)
+        self.remaining_ops_per_machine = np.zeros(
+            (dispatcher.instance.num_machines, 1), dtype=int
+        )
+        self.remaining_ops_per_job = np.zeros(
+            (dispatcher.instance.num_jobs, 1), dtype=int
+        )
+        super().__init__(dispatcher, feature_types, feature_size=1)
+
+    def initialize_features(self):
+        self._initialize_remaining_operations()
+
+    def update(self, scheduled_operation: ScheduledOperation):
+        if FeatureType.OPERATIONS in self.features:
+            # operation_id = scheduled_operation.operation.operation_id
+            # self.features[FeatureType.OPERATIONS][operation_id, 0] = 1
+            completed_operations = [
+                op.operation_id
+                for op in self.dispatcher.completed_operations()
+            ]
+            self.features[FeatureType.OPERATIONS][completed_operations, 0] = 1
+        if FeatureType.MACHINES in self.features:
+            machine_id = scheduled_operation.machine_id
+            self.remaining_ops_per_machine[machine_id, 0] -= 1
+            is_completed = self.remaining_ops_per_machine[machine_id, 0] == 0
+            self.features[FeatureType.MACHINES][machine_id, 0] = is_completed
+        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
+
+    def _initialize_remaining_operations(self):
+        remaining_ops_observer = self._get_remaining_operations_observer(
+            self.dispatcher, self.features
+        )
+        if remaining_ops_observer is not None:
+            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()
+                )
+            return
+
+        # If there is no remaining operations observer, we need to
+        # compute the remaining operations ourselves.
+        # We iterate over all operations using scheduled_operations
+        # instead of uncompleted_operations, because in this case
+        # they will output the same operations, and the former is slightly
+        # more efficient.
+        for operation in self.dispatcher.unscheduled_operations():
+            if FeatureType.JOBS in self.features:
+                self.remaining_ops_per_job[operation.job_id, 0] += 1
+            if FeatureType.MACHINES in self.features:
+                self.remaining_ops_per_machine[operation.machine_id, 0] += 1
+
+    def _get_remaining_operations_observer(
+        self, dispatcher: Dispatcher, feature_types: Iterable[FeatureType]
+    ) -> RemainingOperationsObserver | None:
+        for observer in dispatcher.subscribers:
+            if not isinstance(observer, RemainingOperationsObserver):
+                continue
+            has_same_features = all(
+                feature_type in observer.features
+                for feature_type in feature_types
+            )
+            if has_same_features:
+                return observer
+        return None

job_shop_lib/dispatching/feature_observers/is_ready_observer.py

@@ -0,0 +1,40 @@
+"""Home of the `IsReadyObserver` class."""
+
+from job_shop_lib.dispatching import Dispatcher
+from job_shop_lib.dispatching.feature_observers import (
+    FeatureObserver,
+    FeatureType,
+)
+
+
+class IsReadyObserver(FeatureObserver):
+    """Feature creator that adds a binary feature indicating if the operation
+    is ready to be dispatched."""
+
+    def __init__(
+        self,
+        dispatcher: Dispatcher,
+        feature_types: list[FeatureType] | FeatureType | None = None,
+        subscribe: bool = True,
+    ):
+        super().__init__(
+            dispatcher, feature_types, feature_size=1, subscribe=subscribe
+        )
+
+    def initialize_features(self):
+        self.set_features_to_zero()
+        for feature_type, feature in self.features.items():
+            node_ids = self._get_ready_nodes(feature_type)
+            feature[node_ids, 0] = 1.0
+
+    def _get_ready_nodes(self, feature_type: FeatureType) -> list[int]:
+        mapping = {
+            FeatureType.OPERATIONS: self._get_ready_operation_nodes,
+            FeatureType.MACHINES: self.dispatcher.available_machines,
+            FeatureType.JOBS: self.dispatcher.available_jobs,
+        }
+        return mapping[feature_type]()
+
+    def _get_ready_operation_nodes(self) -> list[int]:
+        available_operations = self.dispatcher.available_operations()
+        return [operation.operation_id for operation in available_operations]

job_shop_lib/dispatching/feature_observers/is_scheduled_observer.py

@@ -0,0 +1,34 @@
+"""Home of the `IsScheduledObserver` class."""
+
+from job_shop_lib import ScheduledOperation
+from job_shop_lib.dispatching.feature_observers import (
+    FeatureObserver,
+    FeatureType,
+)
+
+
+class IsScheduledObserver(FeatureObserver):
+    """Observer that updates features based on scheduling operations.
+
+    This observer tracks which operations have been scheduled and updates
+    feature matrices accordingly. It updates a feature in the
+    `FeatureType.OPERATIONS` matrix to indicate that an operation has been
+    scheduled. Additionally, it counts the number of uncompleted but
+    scheduled operations for each machine and job, updating the respective
+    `FeatureType.MACHINES` and `FeatureType.JOBS` feature matrices.
+    """
+
+    def update(self, scheduled_operation: ScheduledOperation):
+        if FeatureType.OPERATIONS in self.features:
+            self.features[FeatureType.OPERATIONS][
+                scheduled_operation.operation.operation_id, 0
+            ] = 1.0
+
+        ongoing_operations = self.dispatcher.ongoing_operations()
+        self.set_features_to_zero(exclude=FeatureType.OPERATIONS)
+        for scheduled_op in ongoing_operations:
+            if FeatureType.MACHINES in self.features:
+                machine_id = scheduled_op.machine_id
+                self.features[FeatureType.MACHINES][machine_id, 0] += 1.0
+            if FeatureType.JOBS in self.features:
+                self.features[FeatureType.JOBS][scheduled_op.job_id, 0] += 1.0

job_shop_lib/dispatching/feature_observers/position_in_job_observer.py

@@ -0,0 +1,39 @@
+"""Home of the `PositionInJobObserver` class."""
+
+from job_shop_lib.dispatching import Dispatcher
+from job_shop_lib import ScheduledOperation
+from job_shop_lib.dispatching.feature_observers import (
+    FeatureObserver,
+    FeatureType,
+)
+
+
+class PositionInJobObserver(FeatureObserver):
+    """Observer that adds a feature indicating the position of
+    operations in their respective jobs.
+
+    Positions are adjusted dynamically as operations are scheduled.
+    """
+
+    def __init__(self, dispatcher: Dispatcher, subscribe: bool = True):
+        super().__init__(
+            dispatcher,
+            feature_types=[FeatureType.OPERATIONS],
+            feature_size=1,
+            subscribe=subscribe,
+        )
+
+    def initialize_features(self):
+        for operation in self.dispatcher.unscheduled_operations():
+            self.features[FeatureType.OPERATIONS][
+                operation.operation_id, 0
+            ] = operation.position_in_job
+
+    def update(self, scheduled_operation: ScheduledOperation):
+        job = self.dispatcher.instance.jobs[scheduled_operation.job_id]
+        for new_position_in_job, operation in enumerate(
+            job[scheduled_operation.position_in_job + 1 :]
+        ):
+            self.features[FeatureType.OPERATIONS][
+                operation.operation_id, 0
+            ] = new_position_in_job

job_shop_lib/dispatching/feature_observers/remaining_operations_observer.py

@@ -0,0 +1,54 @@
+"""Home of the `RemainingOperationsObserver` class."""
+
+from job_shop_lib import ScheduledOperation
+from job_shop_lib.dispatching import Dispatcher
+from job_shop_lib.dispatching.feature_observers import (
+    FeatureObserver,
+    FeatureType,
+)
+
+
+class RemainingOperationsObserver(FeatureObserver):
+    """Adds a feature indicating the number of remaining operations for each
+    job and machine.
+
+    It does not support FeatureType.OPERATIONS.
+    """
+
+    def __init__(
+        self,
+        dispatcher: Dispatcher,
+        feature_types: list[FeatureType] | FeatureType | None = None,
+        subscribe: bool = True,
+    ):
+        if feature_types is None:
+            feature_types = [FeatureType.MACHINES, FeatureType.JOBS]
+
+        if (
+            feature_types == FeatureType.OPERATIONS
+            or FeatureType.OPERATIONS in feature_types
+        ):
+            raise ValueError("FeatureType.OPERATIONS is not supported.")
+        super().__init__(
+            dispatcher,
+            feature_types=feature_types,
+            feature_size=1,
+            subscribe=subscribe,
+        )
+
+    def initialize_features(self):
+        for operation in self.dispatcher.unscheduled_operations():
+            if FeatureType.JOBS in self.features:
+                self.features[FeatureType.JOBS][operation.job_id, 0] += 1
+            if FeatureType.MACHINES in self.features:
+                self.features[FeatureType.MACHINES][
+                    operation.machine_id, 0
+                ] += 1
+
+    def update(self, scheduled_operation: ScheduledOperation):
+        if FeatureType.JOBS in self.features:
+            job_id = scheduled_operation.job_id
+            self.features[FeatureType.JOBS][job_id, 0] -= 1
+        if FeatureType.MACHINES in self.features:
+            machine_id = scheduled_operation.machine_id
+            self.features[FeatureType.MACHINES][machine_id, 0] -= 1

job_shop_lib/graphs/build_disjunctive_graph.py

@@ -23,6 +23,26 @@ from job_shop_lib.graphs import JobShopGraph, EdgeType, NodeType, Node
 
 
 def build_disjunctive_graph(instance: JobShopInstance) -> JobShopGraph:
+    """Builds and returns a disjunctive graph for the given job shop instance.
+
+    This function creates a complete disjunctive graph from a JobShopInstance.
+    It starts by initializing a JobShopGraph object and proceeds by adding
+    disjunctive edges between operations using the same machine, conjunctive
+    edges between successive operations in the same job, and finally, special
+    source and sink nodes with their respective edges to and from all other
+    operations.
+
+    Edges have a "type" attribute indicating whether they are disjunctive or
+    conjunctive.
+
+    Args:
+        instance (JobShopInstance): The job shop instance for which to build
+        the graph.
+
+    Returns:
+        JobShopGraph: A JobShopGraph object representing the disjunctive graph
+        of the job shop scheduling problem.
+    """
     graph = JobShopGraph(instance)
     add_disjunctive_edges(graph)
     add_conjunctive_edges(graph)

job_shop_lib/job_shop_instance.py

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