job-shop-lib 0.4.0__py3-none-any.whl → 0.5.1__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/generation/__init__.py

@@ -0,0 +1,11 @@
+"""Package for generating job shop instances."""
+
+from job_shop_lib.generation.instance_generator import InstanceGenerator
+from job_shop_lib.generation.general_instance_generator import (
+    GeneralInstanceGenerator,
+)
+
+__all__ = [
+    "InstanceGenerator",
+    "GeneralInstanceGenerator",
+]

job_shop_lib/generation/general_instance_generator.py

@@ -0,0 +1,169 @@
+"""Home of the `BasicGenerator` class."""
+
+import random
+
+from job_shop_lib import JobShopInstance, Operation
+from job_shop_lib.generation import InstanceGenerator
+
+
+class GeneralInstanceGenerator(InstanceGenerator):
+    """Generates instances for job shop problems.
+
+    This class is designed to be versatile, enabling the creation of various
+    job shop instances without the need for multiple dedicated classes.
+
+    It supports customization of the number of jobs, machines, operation
+    durations, and more.
+
+    The class supports both single instance generation and iteration over
+    multiple instances, controlled by the `iteration_limit` parameter. It
+    implements the iterator protocol, allowing it to be used in a `for` loop.
+
+    Note:
+        When used as an iterator, the generator will produce instances until it
+        reaches the specified `iteration_limit`. If `iteration_limit` is None,
+        it will continue indefinitely.
+
+    Attributes:
+        num_jobs_range:
+            The range of the number of jobs to generate. If a single
+            int is provided, it is used as both the minimum and maximum.
+        duration_range:
+            The range of durations for each operation.
+        num_machines_range:
+            The range of the number of machines available. If a
+            single int is provided, it is used as both the minimum and maximum.
+        machines_per_operation:
+            Specifies how many machines each operation
+            can be assigned to. If a single int is provided, it is used for
+            all operations.
+        allow_less_jobs_than_machines:
+            If True, allows generating instances where the number of jobs is
+            less than the number of machines.
+        allow_recirculation:
+            If True, a job can visit the same machine more than once.
+        name_suffix:
+            A suffix to append to each instance's name for identification.
+        seed:
+            Seed for the random number generator to ensure reproducibility.
+    """
+
+    def __init__(  # pylint: disable=too-many-arguments
+        self,
+        num_jobs: int | tuple[int, int] = (10, 20),
+        num_machines: int | tuple[int, int] = (5, 10),
+        duration_range: tuple[int, int] = (1, 99),
+        allow_less_jobs_than_machines: bool = True,
+        allow_recirculation: bool = False,
+        machines_per_operation: int | tuple[int, int] = 1,
+        name_suffix: str = "classic_generated_instance",
+        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,
+            duration_range=duration_range,
+            name_suffix=name_suffix,
+            seed=seed,
+            iteration_limit=iteration_limit,
+        )
+        if isinstance(machines_per_operation, int):
+            machines_per_operation = (
+                machines_per_operation,
+                machines_per_operation,
+            )
+        self.machines_per_operation = machines_per_operation
+
+        self.allow_less_jobs_than_machines = allow_less_jobs_than_machines
+        self.allow_recirculation = allow_recirculation
+        self.name_suffix = name_suffix
+
+        if seed is not None:
+            random.seed(seed)
+
+    def generate(self) -> JobShopInstance:
+        """Generates a single job shop instance"""
+        num_jobs = random.randint(*self.num_jobs_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)
+
+        jobs = []
+        available_machines = list(range(num_machines))
+        for _ in range(num_jobs):
+            job = []
+            for _ in range(num_machines):
+                operation = self.create_random_operation(available_machines)
+                job.append(operation)
+            jobs.append(job)
+            available_machines = list(range(num_machines))
+
+        return JobShopInstance(jobs=jobs, name=self._next_name())
+
+    def create_random_operation(
+        self, available_machines: list[int] | None = None
+    ) -> Operation:
+        """Creates a random operation with the given available machines.
+
+        Args:
+            available_machines:
+                A list of available machine_ids to choose from.
+                If None, all machines are available.
+        """
+        duration = random.randint(*self.duration_range)
+
+        if self.machines_per_operation[1] > 1:
+            machines = self._choose_multiple_machines()
+            return Operation(machines=machines, duration=duration)
+
+        machine_id = self._choose_one_machine(available_machines)
+        return Operation(machines=machine_id, duration=duration)
+
+    def _choose_multiple_machines(self) -> list[int]:
+        num_machines = random.randint(*self.machines_per_operation)
+        available_machines = list(range(num_machines))
+        machines = []
+        for _ in range(num_machines):
+            machine = random.choice(available_machines)
+            machines.append(machine)
+            available_machines.remove(machine)
+        return machines
+
+    def _choose_one_machine(
+        self, available_machines: list[int] | None = None
+    ) -> int:
+        if available_machines is None:
+            _, max_num_machines = self.num_machines_range
+            available_machines = list(range(max_num_machines))
+
+        machine_id = random.choice(available_machines)
+        if not self.allow_recirculation:
+            available_machines.remove(machine_id)
+
+        return machine_id