job-shop-lib 1.3.0__py3-none-any.whl → 1.6.0__py3-none-any.whl

job_shop_lib/dispatching/_dispatcher.py

@@ -25,9 +25,8 @@ def no_setup_time_calculator(
 ) -> int:
     """Default start time calculator that implements the standard behavior.
 
-    The start time is the maximum of the next available time for the
-    machine and the next available time for the job to which the
-    operation belongs.
+    The start time is the maximum of the machine's next available time, the
+    job's next available time, and the operation's release date.
 
     Args:
         dispatcher:
@@ -44,6 +43,7 @@ def no_setup_time_calculator(
     return max(
         dispatcher.machine_next_available_time[machine_id],
         dispatcher.job_next_available_time[operation.job_id],
+        operation.release_date,
     )
 
 
@@ -552,7 +552,9 @@ class Dispatcher:
             for machine_id in operation.machines
         )
         job_start_time = self._job_next_available_time[operation.job_id]
-        return max(machine_earliest_start_time, job_start_time)
+        return max(
+            machine_earliest_start_time, job_start_time, operation.release_date
+        )
 
     def remaining_duration(
         self, scheduled_operation: ScheduledOperation
@@ -632,7 +634,11 @@ class Dispatcher:
     def is_ongoing(self, scheduled_operation: ScheduledOperation) -> bool:
         """Checks if the given operation is currently being processed."""
         current_time = self.current_time()
-        return scheduled_operation.start_time <= current_time
+        return (
+            scheduled_operation.start_time
+            <= current_time
+            < scheduled_operation.end_time
+        )
 
     def next_operation(self, job_id: int) -> Operation:
         """Returns the next operation to be scheduled for the given job.

job_shop_lib/dispatching/_ready_operation_filters.py

@@ -88,6 +88,8 @@ def filter_non_immediate_operations(
     min_start_time = dispatcher.min_start_time(operations)
     immediate_operations: list[Operation] = []
     for operation in operations:
+        if operation.release_date > min_start_time:
+            continue
         start_time = dispatcher.earliest_start_time(operation)
         if start_time == min_start_time:
             immediate_operations.append(operation)

job_shop_lib/dispatching/feature_observers/__init__.py

@@ -14,6 +14,7 @@ dispatcher.
     PositionInJobObserver
     RemainingOperationsObserver
     IsCompletedObserver
+    DatesObserver
     FeatureObserverType
     feature_observer_factory
     FeatureObserverConfig
@@ -41,6 +42,7 @@ from ._is_scheduled_observer import IsScheduledObserver
 from ._position_in_job_observer import PositionInJobObserver
 from ._remaining_operations_observer import RemainingOperationsObserver
 from ._is_completed_observer import IsCompletedObserver
+from ._dates_observer import DatesObserver
 from ._factory import (
     FeatureObserverType,
     feature_observer_factory,
@@ -60,6 +62,7 @@ __all__ = [
     "PositionInJobObserver",
     "RemainingOperationsObserver",
     "IsCompletedObserver",
+    "DatesObserver",
     "FeatureObserverType",
     "feature_observer_factory",
     "FeatureObserverConfig",

job_shop_lib/dispatching/feature_observers/_dates_observer.py

@@ -0,0 +1,162 @@
+"""Home of the `DatesObserver` class."""
+
+from typing import Literal
+
+import numpy as np
+
+from job_shop_lib import ScheduledOperation, JobShopInstance
+from job_shop_lib.dispatching import Dispatcher
+from job_shop_lib.dispatching.feature_observers import (
+    FeatureObserver,
+    FeatureType,
+)
+
+Attribute = Literal["release_date", "deadline", "due_date"]
+
+
+class DatesObserver(FeatureObserver):
+    """Observes time-related attributes of operations.
+
+    This observer tracks attributes like release date, deadline, and
+    due date for each operation in the job shop instance. The attributes to
+    be observed can be specified during initialization.
+
+    The values are stored in a numpy array of shape ``(num_operations,
+    num_attributes)``, where ``num_attributes`` is the number of attributes
+    being observed.
+
+    All attributes are updated based on the current time of the dispatcher so
+    that they reflect the relative time remaining until the event occurs:
+    (attribute - current_time). This means that the values will be negative if
+    the event is in the past.
+
+    Args:
+        dispatcher:
+            The :class:`~job_shop_lib.dispatching.Dispatcher` to observe.
+        subscribe:
+            If ``True``, the observer is subscribed to the dispatcher upon
+            initialization. Otherwise, the observer must be subscribed later
+            or manually updated.
+        attributes_to_observe:
+            A list of attributes to observe. If ``None``, all available time
+            attributes (release_date, deadline, due_date) will be
+            observed, provided they exist in the instance.
+    """
+
+    _supported_feature_types = [FeatureType.OPERATIONS]
+
+    __slots__ = {
+        "attributes_to_observe": "List of attributes to observe.",
+        "_attribute_map": "Maps attributes to their column index.",
+    }
+
+    def __init__(
+        self,
+        dispatcher: Dispatcher,
+        *,
+        subscribe: bool = True,
+        attributes_to_observe: list[Attribute] | None = None,
+        feature_types: FeatureType | list[FeatureType] | None = None,
+    ):
+        self.attributes_to_observe = self._determine_attributes_to_observe(
+            dispatcher.instance, attributes_to_observe
+        )
+        self._attribute_map = {
+            attr: i for i, attr in enumerate(self.attributes_to_observe)
+        }
+        self._previous_current_time = 0
+        super().__init__(
+            dispatcher,
+            subscribe=subscribe,
+            feature_types=feature_types,
+        )
+
+    @property
+    def feature_sizes(self) -> dict[FeatureType, int]:
+        return {
+            FeatureType.OPERATIONS: len(self.attributes_to_observe),
+        }
+
+    @property
+    def attribute_map(self) -> dict[Attribute, int]:
+        """Maps attributes to their column index in the features array."""
+        return self._attribute_map
+
+    def initialize_features(self):
+        """Initializes the features for the operations.
+
+        This method sets up the features for the operations based on the
+        attributes to observe. It creates a numpy array with the shape
+        (num_operations, num_attributes) and fills it with the corresponding
+        values from the job shop instance. Note that the matrix may contain
+        ``np.nan`` values for operations that do not have deadlines or
+        due dates.
+
+        .. seealso::
+            - :meth:`job_shop_lib.JobShopInstance.release_dates_matrix_array`
+            - :meth:`job_shop_lib.JobShopInstance.deadlines_matrix_array`
+            - :meth:`job_shop_lib.JobShopInstance.due_dates_matrix_array`
+        """
+        self.features = {
+            FeatureType.OPERATIONS: np.zeros(
+                (
+                    self.dispatcher.instance.num_operations,
+                    len(self.attributes_to_observe),
+                ),
+                dtype=np.float32,
+            )
+        }
+        self._previous_current_time = self.dispatcher.current_time()
+        release_dates_matrix = (
+            self.dispatcher.instance.release_dates_matrix_array
+        )
+        valid_operations_mask = ~np.isnan(release_dates_matrix.flatten())
+
+        for attr, col_idx in self._attribute_map.items():
+            matrix = getattr(self.dispatcher.instance, f"{attr}s_matrix_array")
+            values = np.array(matrix).flatten()
+            valid_values = values[valid_operations_mask]
+            self.features[FeatureType.OPERATIONS][:, col_idx] = valid_values
+
+    def update(self, scheduled_operation: ScheduledOperation):
+        """Updates the features based on the scheduled operation.
+
+        This method updates the features by subtracting the current time from
+        the initial release date, deadline, and due date attributes of the
+        operations.
+
+        Args:
+            scheduled_operation:
+                The scheduled operation that has just been processed. It is
+                not used in this observer, but is required by the
+                :meth:`FeatureObserver.update` method.
+        """
+        current_time = self.dispatcher.current_time()
+        elapsed_time = current_time - self._previous_current_time
+        self._previous_current_time = current_time
+        cols = [
+            self._attribute_map[attr]
+            for attr in self.attributes_to_observe
+        ]
+        self.features[FeatureType.OPERATIONS][:, cols] -= elapsed_time
+
+    def _determine_attributes_to_observe(
+        self,
+        instance: JobShopInstance,
+        attributes_to_observe: list[Attribute] | None,
+    ) -> list[Attribute]:
+        if attributes_to_observe:
+            return attributes_to_observe
+
+        default_attributes: list[Attribute] = []
+        if instance.has_release_dates:
+            default_attributes.append("release_date")
+        if instance.has_deadlines:
+            default_attributes.append("deadline")
+        if instance.has_due_dates:
+            default_attributes.append("due_date")
+        return default_attributes
+
+    def reset(self):
+        """Calls :meth:`initialize_features`"""
+        self.initialize_features()

job_shop_lib/dispatching/feature_observers/_duration_observer.py

@@ -77,12 +77,13 @@ class DurationObserver(FeatureObserver):
             self.features[FeatureType.JOBS][job_id, 0] = job_duration
 
     def _update_operation_durations(
-        self, scheduled_operation: ScheduledOperation
+        self, unused_scheduled_operation: ScheduledOperation
     ):
-        operation_id = scheduled_operation.operation.operation_id
-        self.features[FeatureType.OPERATIONS][operation_id, 0] = (
-            self.dispatcher.remaining_duration(scheduled_operation)
-        )
+        for scheduled_operation in self.dispatcher.ongoing_operations():
+            operation_id = scheduled_operation.operation.operation_id
+            self.features[FeatureType.OPERATIONS][operation_id, 0] = (
+                self.dispatcher.remaining_duration(scheduled_operation)
+            )
 
     def _update_machine_durations(
         self, scheduled_operation: ScheduledOperation

job_shop_lib/dispatching/rules/__init__.py

@@ -18,6 +18,7 @@ Dispatching rules:
     :nosignatures:
 
     shortest_processing_time_rule
+    largest_processing_time_rule
     first_come_first_served_rule
     most_work_remaining_rule
     most_operations_remaining_rule
@@ -32,6 +33,7 @@ Dispatching rule scorers:
     :nosignatures:
 
     shortest_processing_time_score
+    largest_processing_time_score
     first_come_first_served_score
     MostWorkRemainingScorer
     most_operations_remaining_score
@@ -45,6 +47,8 @@ from ._dispatching_rules_functions import (
     most_work_remaining_rule,
     most_operations_remaining_rule,
     random_operation_rule,
+    largest_processing_time_score,
+    largest_processing_time_rule,
     score_based_rule,
     score_based_rule_with_tie_breaker,
     shortest_processing_time_score,
@@ -78,6 +82,8 @@ __all__ = [
     "most_work_remaining_rule",
     "most_operations_remaining_rule",
     "random_operation_rule",
+    "largest_processing_time_score",
+    "largest_processing_time_rule",
     "score_based_rule",
     "score_based_rule_with_tie_breaker",
     "observer_based_most_work_remaining_rule",

job_shop_lib/dispatching/rules/_dispatching_rule_factory.py

@@ -17,6 +17,7 @@ from job_shop_lib.dispatching.rules import (
     most_operations_remaining_rule,
     random_operation_rule,
     most_work_remaining_rule,
+    largest_processing_time_rule,
 )
 
 
@@ -24,6 +25,7 @@ class DispatchingRuleType(str, Enum):
     """Enumeration of dispatching rules for the job shop scheduling problem."""
 
     SHORTEST_PROCESSING_TIME = "shortest_processing_time"
+    LARGEST_PROCESSING_TIME = "largest_processing_time"
     FIRST_COME_FIRST_SERVED = "first_come_first_served"
     MOST_WORK_REMAINING = "most_work_remaining"
     MOST_OPERATIONS_REMAINING = "most_operations_remaining"
@@ -62,6 +64,9 @@ def dispatching_rule_factory(
         DispatchingRuleType.SHORTEST_PROCESSING_TIME: (
             shortest_processing_time_rule
         ),
+        DispatchingRuleType.LARGEST_PROCESSING_TIME: (
+            largest_processing_time_rule
+        ),
         DispatchingRuleType.FIRST_COME_FIRST_SERVED: (
             first_come_first_served_rule
         ),

job_shop_lib/dispatching/rules/_dispatching_rules_functions.py

@@ -26,6 +26,37 @@ def shortest_processing_time_rule(dispatcher: Dispatcher) -> Operation:
     )
 
 
+def largest_processing_time_rule(dispatcher: Dispatcher) -> Operation:
+    """Dispatches the operation with the longest duration."""
+    return max(
+        dispatcher.available_operations(),
+        key=lambda operation: operation.duration,
+    )
+
+
+def largest_processing_time_score(dispatcher: Dispatcher) -> list[int]:
+    """Scores each job based on the duration of the next operation.
+
+    The score is the duration of the next operation in each job.
+    Jobs with longer next operations will have higher scores.
+
+    Args:
+        dispatcher:
+            The :class:`~job_shop_lib.dispatching.Dispatcher` instance
+            containing the job shop instance and the current state of the
+            schedule.
+
+    Returns:
+        A list of scores for each job, where the score is the duration of
+        the next operation in that job.
+    """
+    num_jobs = dispatcher.instance.num_jobs
+    scores = [0] * num_jobs
+    for operation in dispatcher.available_operations():
+        scores[operation.job_id] = operation.duration
+    return scores
+
+
 def first_come_first_served_rule(dispatcher: Dispatcher) -> Operation:
     """Dispatches the operation with the lowest position in job."""
     return min(

job_shop_lib/generation/_utils.py

@@ -98,9 +98,7 @@ def generate_machine_matrix_without_recirculation(
         (num_jobs, 1),
     )
     # Shuffle the columns:
-    machine_matrix = np.apply_along_axis(
-        rng.permutation, 1, machine_matrix
-    )
+    machine_matrix = np.apply_along_axis(rng.permutation, 1, machine_matrix)
     return machine_matrix
 
 

job_shop_lib/metaheuristics/__init__.py

@@ -0,0 +1,61 @@
+"""Metaheuristic algorithms for solving job shop scheduling problems.
+
+This module provides implementations of various metaheuristic optimization
+algorithms designed to solve the job shop scheduling problem.
+
+Metaheuristics are particularly well-suited for JSSP due to their ability to:
+
+- Handle large solution spaces efficiently
+- Escape local optima through stochastic mechanisms
+- Balance exploration and exploitation of the search space
+- Provide good quality solutions within reasonable computational time
+
+Currently implemented algorithms:
+
+- Simulated annealing: A probabilistic technique that accepts worse
+  solutions with decreasing probability to escape local optima
+
+The module aims to contain implementations of other
+metaheuristic algorithms such as genetic algorithms, particle swarm
+optimization, tabu search, etc. Feel free to open an issue if you want to
+contribute!
+
+.. autosummary::
+    :nosignatures:
+
+    JobShopAnnealer
+    SimulatedAnnealingSolver
+    NeighborGenerator
+    swap_adjacent_operations
+    swap_in_critical_path
+    swap_random_operations
+    ObjectiveFunction
+    get_makespan_with_penalties_objective
+
+"""
+
+from job_shop_lib.metaheuristics._objective_functions import (
+    ObjectiveFunction,
+    get_makespan_with_penalties_objective,
+)
+from job_shop_lib.metaheuristics._neighbor_generators import (
+    NeighborGenerator,
+    swap_adjacent_operations,
+    swap_in_critical_path,
+    swap_random_operations,
+)
+from job_shop_lib.metaheuristics._job_shop_annealer import JobShopAnnealer
+from job_shop_lib.metaheuristics._simulated_annealing_solver import (
+    SimulatedAnnealingSolver,
+)
+
+__all__ = [
+    "JobShopAnnealer",
+    "SimulatedAnnealingSolver",
+    "NeighborGenerator",
+    "swap_adjacent_operations",
+    "swap_in_critical_path",
+    "swap_random_operations",
+    "ObjectiveFunction",
+    "get_makespan_with_penalties_objective",
+]

job_shop_lib/metaheuristics/_job_shop_annealer.py

@@ -0,0 +1,229 @@
+import random
+import math
+import time
+
+import simanneal
+
+from job_shop_lib import JobShopInstance, Schedule
+from job_shop_lib.exceptions import ValidationError
+from job_shop_lib.metaheuristics import (
+    NeighborGenerator,
+    ObjectiveFunction,
+    swap_in_critical_path,
+    get_makespan_with_penalties_objective,
+)
+
+
+class JobShopAnnealer(simanneal.Annealer):
+    """Helper class for the :class:`SimulatedAnnealingSolver`.
+
+    It uses `simanneal <https://github.com/perrygeo/simanneal>`_ as the
+    backend.
+
+    In the context of the job shop scheduling problem, simulated annealing is
+    particularly useful for improving previous solutions.
+
+    The neighbor move is pluggable via a ``neighbor_generator`` function. By
+    default it uses :func:`swap_in_critical_path`, but any function that takes
+    a schedule and a random generator and returns a new schedule can be
+    provided to tailor the exploration of the search space.
+
+    The process involves iteratively exploring the solution space:
+
+    1. A random move is made to alter the current state. This is done by
+       swapping two operations in the sequence of a machine.
+    2. The "energy" of the new state is evaluated using an objective function.
+       With the default objective function, the energy is calculated as the
+       makespan of the schedule plus penalties for any constraint violations
+       (such as deadlines and due dates). See
+       :func:`get_makespan_with_penalties_objective` for details. You can
+       create custom objective functions by implementing the
+       :class:`ObjectiveFunction` interface, which takes a schedule and returns
+       a float representing the energy of that schedule.
+    3. The new state is accepted if it has lower energy (a better solution).
+       If it has higher energy, it might still be accepted with a certain
+       probability, which depends on the current "temperature". The
+       temperature decreases over time, reducing the chance of accepting
+       worse solutions as the algorithm progresses. This helps to avoid
+       getting stuck in local optima.
+
+    This is repeated until the solution converges or a maximum number of
+    steps is reached.
+
+    Tuning the annealer is crucial for performance. The base
+    ``simanneal.Annealer`` class provides parameters that can be adjusted:
+
+    - ``Tmax``: Maximum (starting) temperature (default: 25000.0).
+    - ``Tmin``: Minimum (ending) temperature (default: 2.5).
+    - ``steps``: Number of iterations (default: 50000).
+    - ``updates``: Number of progress updates (default: 100).
+
+    A good starting point is to set ``Tmax`` to a value that accepts about 98%
+    of moves and ``Tmin`` to a value where the solution no longer improves.
+    The number of ``steps`` should be large enough to explore the search space
+    thoroughly.
+
+    These parameters can be set on the annealer instance. For example:
+    ``annealer.Tmax = 12000.0``
+
+    Alternatively, this class provides an ``auto`` method to find reasonable
+    parameters based on a desired runtime:
+    ``auto_schedule = annealer.auto(minutes=1)``
+    ``annealer.set_schedule(auto_schedule)``
+
+    Attributes:
+        instance:
+            The job shop instance to solve.
+        random_generator:
+            Random generator for reproducibility.
+        neighbor_generator:
+            Function used to generate neighbors from the current schedule.
+            Defaults to :func:`swap_in_critical_path`.
+        objective_function:
+            Function that computes the energy of the schedule. If ``None``,
+            it defaults to :func:`get_makespan_with_penalties_objective`.
+            This function receives a schedule and returns the energy that will
+            be minimized by the annealer.
+
+    Args:
+        instance:
+            The job shop instance to solve. It retrieves the jobs and
+            machines from the instance and uses them to create the schedule.
+        initial_state:
+            Initial state of the schedule as a list of lists, where each
+            sublist represents the operations of a job.
+        seed:
+            Random seed for reproducibility. If ``None``, random behavior
+            will be non-deterministic.
+        neighbor_generator:
+            Function that receives the current schedule and a random generator
+            and returns a new schedule to explore. Defaults to
+            :func:`swap_in_critical_path`. Use this to plug in custom
+            neighborhoods (e.g., adjacent swaps).
+        objective_function:
+            Function that computes the energy of the schedule. If ``None``,
+            it defaults to :func:`get_makespan_with_penalties_objective`.
+            This callable receives a :class:`~job_shop_lib.Schedule` and
+            returns a float that will be minimized by the annealer.
+    """
+
+    copy_strategy = "method"
+
+    def __init__(
+        self,
+        instance: JobShopInstance,
+        initial_state: Schedule,
+        *,
+        seed: int | None = None,
+        neighbor_generator: NeighborGenerator = swap_in_critical_path,
+        objective_function: ObjectiveFunction | None = None,
+    ):
+        super().__init__(initial_state)
+        self.instance = instance
+        if objective_function is None:
+            self.objective_function = get_makespan_with_penalties_objective()
+        else:
+            self.objective_function = objective_function
+        self.random_generator = random.Random(seed)
+        self.neighbor_generator = neighbor_generator
+
+    def _get_state(self) -> Schedule:
+        """Returns the current state of the annealer.
+
+        This method facilitates type checking.
+        """
+        return self.state
+
+    def move(self) -> None:
+        """Generates a neighbor state using the configured neighbor generator.
+
+        Delegates to ``self.neighbor_generator`` with the current schedule and
+        the internal random generator, enabling pluggable neighborhoods.
+        """
+        self.state = self.neighbor_generator(
+            self._get_state(), self.random_generator
+        )
+
+    def anneal(self) -> tuple[Schedule, float]:
+        """Minimizes the energy of a system by simulated annealing.
+
+        Overrides the ``anneal`` method from the base class to use the
+        random  generator defined in the constructor.
+
+        Returns:
+            The best state and energy found during the annealing process.
+        """
+        step = 0
+        self.start = time.time()
+
+        # Precompute factor for exponential cooling from Tmax to Tmin
+        if self.Tmin <= 0.0:
+            raise ValidationError(
+                "Exponential cooling requires a minimum "
+                "temperature greater than zero."
+            )
+        t_factor = -math.log(self.Tmax / self.Tmin)
+
+        # Note initial state
+        t = self.Tmax
+        current_energy = self.energy()
+        prev_state = self.copy_state(self.state)
+        prev_energy = current_energy
+        self.best_state = self.copy_state(self.state)
+        self.best_energy = current_energy
+        trials, accepts, improves = 0, 0, 0
+        update_wave_length = 0  # not used, but avoids pylint warning
+        if self.updates > 0:
+            update_wave_length = self.steps / self.updates
+            self.update(step, t, current_energy, None, None)
+
+        # Attempt moves to new states
+        while step < self.steps and not self.user_exit:
+            step += 1
+            t = self.Tmax * math.exp(t_factor * step / self.steps)
+            self.move()
+            current_energy = self.energy()
+            delta_e = current_energy - prev_energy
+            trials += 1
+            if (
+                delta_e > 0.0
+                and math.exp(-delta_e / t) < self.random_generator.random()
+            ):
+                # Restore previous state
+                self.state = self.copy_state(prev_state)
+                current_energy = prev_energy
+            else:
+                # Accept new state and compare to best state
+                accepts += 1
+                if delta_e < 0.0:
+                    improves += 1
+                prev_state = self.copy_state(self.state)
+                prev_energy = current_energy
+                if current_energy < self.best_energy:
+                    self.best_state = self.copy_state(self.state)
+                    self.best_energy = current_energy
+            if self.updates < 1:
+                continue
+            if (step // update_wave_length) > (
+                (step - 1) // update_wave_length
+            ):
+                self.update(
+                    step,
+                    t,
+                    current_energy,
+                    accepts / trials,
+                    improves / trials,
+                )
+                trials, accepts, improves = 0, 0, 0
+
+        self.state = self.copy_state(self.best_state)
+        if self.save_state_on_exit:
+            self.save_state()
+
+        return self.best_state, self.best_energy
+
+    def energy(self) -> float:
+        """Computes the energy of the current schedule using the objective
+        function provided."""
+        schedule = self._get_state()
+        return self.objective_function(schedule)