job-shop-lib 1.5.0__py3-none-any.whl → 1.6.0__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.5.0"
+__version__ = "1.6.0"
 
 __all__ = [
     "Operation",

job_shop_lib/_base_solver.py

@@ -15,13 +15,13 @@ Solver = Callable[[JobShopInstance], Schedule]
 class BaseSolver(abc.ABC):
     """Base class for all solvers implemented as classes.
 
-    A `Solver` is any `Callable` that takes a `JobShopInstance` and returns a
-    `Schedule`. Therefore, solvers can be implemented as functions or as
-    classes. This class is provided as a base class for solvers implemented as
-    classes. It provides a default implementation of the `__call__` method that
-    measures the time taken to solve the instance and stores it in the
-    schedule's metadata under the key "elapsed_time" if it is not already
-    present.
+    A ``Solver`` is any ``Callable`` that takes a :class:`JobShopInstance` and
+    returns a :class:`Schedule`. Therefore, solvers can be implemented as
+    functions or as classes. This class is provided as a base class for solvers
+    implemented as classes. It provides a default implementation of the
+    ``__call__`` method that measures the time taken to solve the instance
+    and stores it in the schedule's metadata under the key "elapsed_time" if
+    it is not alreadypresent.
     """
 
     @abc.abstractmethod

job_shop_lib/_schedule.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 from typing import Any, TYPE_CHECKING
 from collections import deque
 
-from job_shop_lib import ScheduledOperation, JobShopInstance
+from job_shop_lib import ScheduledOperation, JobShopInstance, Operation
 from job_shop_lib.exceptions import ValidationError
 
 if TYPE_CHECKING:
@@ -53,6 +53,19 @@ class Schedule:
             "schedule. It can be used to store information about the "
             "algorithm that generated the schedule, for example."
         ),
+        "operation_to_scheduled_operation": (
+            "A dictionary that maps an :class:`Operation` to its "
+            ":class:`ScheduledOperation` in the schedule. This is used to "
+            "quickly find the scheduled operation associated with a given "
+            "operation."
+        ),
+        "num_scheduled_operations": (
+            "The number of operations that have been scheduled so far."
+        ),
+        "operation_with_latest_end_time": (
+            "The :class:`ScheduledOperation` with the latest end time. "
+            "This is used to quickly find the last operation in the schedule."
+        ),
     }
 
     def __init__(
@@ -69,6 +82,25 @@ class Schedule:
         self.instance: JobShopInstance = instance
         self._schedule = schedule
         self.metadata: dict[str, Any] = metadata
+        self.operation_to_scheduled_operation: dict[
+            Operation, ScheduledOperation
+        ] = {
+            scheduled_op.operation: scheduled_op
+            for machine_schedule in schedule
+            for scheduled_op in machine_schedule
+        }
+        self.num_scheduled_operations = sum(
+            len(machine_schedule) for machine_schedule in schedule
+        )
+        self.operation_with_latest_end_time: ScheduledOperation | None = max(
+            (
+                scheduled_op
+                for machine_schedule in schedule
+                for scheduled_op in machine_schedule
+            ),
+            key=lambda op: op.end_time,  # type: ignore[union-attr]
+            default=None,
+        )
 
     def __repr__(self) -> str:
         return str(self.schedule)
@@ -84,11 +116,6 @@ class Schedule:
         Schedule.check_schedule(new_schedule)
         self._schedule = new_schedule
 
-    @property
-    def num_scheduled_operations(self) -> int:
-        """The number of operations that have been scheduled so far."""
-        return sum(len(machine_schedule) for machine_schedule in self.schedule)
-
     def to_dict(self) -> dict:
         """Returns a dictionary representation of the schedule.
 
@@ -106,15 +133,9 @@ class Schedule:
                 - **"metadata"**: A dictionary with additional information
                   about the schedule.
         """
-        job_sequences: list[list[int]] = []
-        for machine_schedule in self.schedule:
-            job_sequences.append(
-                [operation.job_id for operation in machine_schedule]
-            )
-
         return {
             "instance": self.instance.to_dict(),
-            "job_sequences": job_sequences,
+            "job_sequences": self.job_sequences(),
             "metadata": self.metadata,
         }
 
@@ -211,20 +232,35 @@ class Schedule:
                 )
         return dispatcher.schedule
 
+    def job_sequences(self) -> list[list[int]]:
+        """Returns the sequence of jobs for each machine in the schedule.
+
+        This method returns a list of lists, where each sublist contains the
+        job ids of the operations scheduled on that machine.
+        """
+        job_sequences: list[list[int]] = []
+        for machine_schedule in self.schedule:
+            job_sequences.append(
+                [operation.job_id for operation in machine_schedule]
+            )
+        return job_sequences
+
     def reset(self):
         """Resets the schedule to an empty state."""
         self.schedule = [[] for _ in range(self.instance.num_machines)]
+        self.operation_to_scheduled_operation = {}
+        self.num_scheduled_operations = 0
+        self.operation_with_latest_end_time = None
 
     def makespan(self) -> int:
         """Returns the makespan of the schedule.
 
         The makespan is the time at which all operations are completed.
         """
-        max_end_time = 0
-        for machine_schedule in self.schedule:
-            if machine_schedule:
-                max_end_time = max(max_end_time, machine_schedule[-1].end_time)
-        return max_end_time
+        last_operation = self.operation_with_latest_end_time
+        if last_operation is None:
+            return 0
+        return last_operation.end_time
 
     def is_complete(self) -> bool:
         """Returns ``True`` if all operations have been scheduled."""
@@ -245,10 +281,25 @@ class Schedule:
                 constraints.
         """
         self._check_start_time_of_new_operation(scheduled_operation)
+
+        # Update attributes:
         self.schedule[scheduled_operation.machine_id].append(
             scheduled_operation
         )
 
+        self.operation_to_scheduled_operation[
+            scheduled_operation.operation
+        ] = scheduled_operation
+
+        self.num_scheduled_operations += 1
+
+        if (
+            self.operation_with_latest_end_time is None
+            or scheduled_operation.end_time
+            > self.operation_with_latest_end_time.end_time
+        ):
+            self.operation_with_latest_end_time = scheduled_operation
+
     def _check_start_time_of_new_operation(
         self,
         new_operation: ScheduledOperation,
@@ -333,3 +384,71 @@ class Schedule:
             [machine_schedule.copy() for machine_schedule in self.schedule],
             **self.metadata,
         )
+
+    def critical_path(self) -> list[ScheduledOperation]:
+        """Returns the critical path of the schedule.
+
+        The critical path is the longest path of dependent operations through
+        the schedule, which determines the makespan. This implementation
+        correctly identifies the path even in non-compact schedules where
+        idle time may exist.
+
+        It works by starting from an operation that determines the makespan
+        and tracing backwards, at each step choosing the predecessor (either
+        from the same job or the same machine) that finished latest.
+        """
+        # 1. Start from the operation that determines the makespan
+        last_scheduled_op = self.operation_with_latest_end_time
+        if last_scheduled_op is None:
+            return []
+
+        critical_path = deque([last_scheduled_op])
+        current_scheduled_op = last_scheduled_op
+
+        # 2. Trace backwards from the last operation
+        while True:
+            job_pred = None
+            machine_pred = None
+
+            # Find job predecessor (the previous operation in the same job)
+            op_idx_in_job = current_scheduled_op.operation.position_in_job
+            if op_idx_in_job > 0:
+                prev_op_in_job = self.instance.jobs[
+                    current_scheduled_op.job_id
+                ][op_idx_in_job - 1]
+                job_pred = self.operation_to_scheduled_operation[
+                    prev_op_in_job
+                ]
+
+            # Find machine predecessor (the previous operation on the same
+            # machine)
+            machine_schedule = self.schedule[current_scheduled_op.machine_id]
+            op_idx_on_machine = machine_schedule.index(current_scheduled_op)
+            if op_idx_on_machine > 0:
+                machine_pred = machine_schedule[op_idx_on_machine - 1]
+
+            # 3. Determine the critical predecessor
+            # The critical predecessor is the one that finished latest, as it
+            # determined the start time of the current operation.
+
+            if job_pred is None and machine_pred is None:
+                # Reached the beginning of the schedule, no more predecessors
+                break
+
+            job_pred_end_time = (
+                job_pred.end_time if job_pred is not None else -1
+            )
+            machine_pred_end_time = (
+                machine_pred.end_time if machine_pred is not None else -1
+            )
+            critical_pred = (
+                job_pred
+                if job_pred_end_time >= machine_pred_end_time
+                else machine_pred
+            )
+            assert critical_pred is not None
+            # Prepend the critical predecessor to the path and continue tracing
+            critical_path.appendleft(critical_pred)
+            current_scheduled_op = critical_pred
+
+        return list(critical_path)

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)

job_shop_lib/metaheuristics/_neighbor_generators.py

@@ -0,0 +1,182 @@
+from collections.abc import Callable
+import random
+
+from job_shop_lib import Schedule, ScheduledOperation
+from job_shop_lib.exceptions import ValidationError
+
+
+NeighborGenerator = Callable[[Schedule, random.Random], Schedule]
+
+_MAX_ATTEMPTS = 1000
+
+
+def _swap_with_index_picker(
+    schedule: Schedule,
+    random_generator: random.Random | None,
+    index_picker: Callable[[list, random.Random], tuple[int, int]],
+) -> Schedule:
+    """Generates a neighbor schedule by swapping two positions chosen by a
+    strategy.
+
+    This private helper applies a swap on a randomly selected machine whose
+    sequence has at least two operations. The actual indices to swap are
+    chosen by the provided picker function. It attempts up to a fixed number
+    of times to produce a valid neighbor. If all attempts fail, it returns
+    the original schedule unchanged.
+
+    Args:
+        schedule:
+            Current schedule to perturb.
+
+        random_generator:
+            Source of randomness. If ``None``, a new generator is created.
+
+        index_picker:
+            Function that receives a machine sequence and a random generator
+            and returns two indices to swap.
+
+    Returns:
+        A valid neighbor schedule if a feasible swap is found, otherwise the
+        original schedule.
+    """
+    if random_generator is None:
+        random_generator = random.Random()
+    job_sequences = schedule.job_sequences()
+    valid_machines = [i for i, seq in enumerate(job_sequences) if len(seq) > 1]
+    if not valid_machines:
+        return schedule
+
+    for _ in range(_MAX_ATTEMPTS):
+        machine_id = random_generator.choice(valid_machines)
+        sequence = job_sequences[machine_id]
+        idx1, idx2 = index_picker(sequence, random_generator)
+        sequence[idx1], sequence[idx2] = sequence[idx2], sequence[idx1]
+        try:
+            return Schedule.from_job_sequences(
+                schedule.instance, job_sequences
+            )
+        except ValidationError:
+            pass
+    return schedule
+
+
+def swap_adjacent_operations(
+    schedule: Schedule, random_generator: random.Random | None = None
+) -> Schedule:
+    """Generates a neighbor schedule by swapping two adjacent operations.
+
+    Selects a machine at random with at least two operations and swaps a pair
+    of adjacent operations in its sequence. Internally tries several times to
+    produce a valid neighbor; if none is found, the original schedule is
+    returned.
+
+    Args:
+        schedule:
+            Current schedule to perturb.
+
+        random_generator:
+            Source of randomness. If ``None``, a new generator is created.
+
+    Returns:
+        A valid neighbor schedule with one adjacent swap applied, or the
+        original schedule if no valid swap is found.
+    """
+
+    def adjacent_picker(seq: list, rng: random.Random) -> tuple[int, int]:
+        idx = rng.randint(0, len(seq) - 2)
+        return idx, idx + 1
+
+    return _swap_with_index_picker(schedule, random_generator, adjacent_picker)
+
+
+def swap_random_operations(
+    schedule: Schedule, random_generator: random.Random | None = None
+) -> Schedule:
+    """Generates a neighbor schedule by swapping two random operations.
+
+    Selects a machine at random with at least two operations and swaps two
+    randomly chosen positions in its sequence. Internally tries several times
+    to produce a valid neighbor; if none is found, the original schedule is
+    returned.
+
+    Args:
+        schedule:
+            Current schedule to perturb.
+
+        random_generator:
+            Source of randomness. If ``None``, a new generator is created.
+
+    Returns:
+        A valid neighbor schedule with one random swap applied, or the
+        original schedule if no valid swap is found.
+    """
+
+    def random_picker(seq: list, rng: random.Random) -> tuple[int, int]:
+        idx1, idx2 = rng.sample(range(len(seq)), 2)
+        return idx1, idx2
+
+    return _swap_with_index_picker(schedule, random_generator, random_picker)
+
+
+def swap_in_critical_path(
+    schedule: Schedule, random_generator: random.Random | None = None
+) -> Schedule:
+    """Generates a neighbor by targeting swaps on the critical path.
+
+    This operator focuses on pairs of consecutive scheduled operations along
+    the current critical path that share the same machine. Swapping such
+    operations directly perturbs the longest-duration chain of precedence
+    and resource constraints that determines the makespan.
+
+    Why target the critical path:
+
+    - The makespan is the length of the critical path; operations not on it
+      typically have slack, so reordering them often does not improve the
+      objective. By contrast, modifying machine order on the critical path
+      can shorten the longest path or unlock constraints that reduce
+      blocking and idle times.
+    - Swapping consecutive critical operations on the same machine always
+      results in a feasible schedule.
+
+    Behavior:
+
+    - Identifies all consecutive pairs on the critical path that run on the
+      same machine and swaps one of them at random.
+    - If no such pairs exist, it falls back to a standard adjacent swap.
+
+    Args:
+        schedule:
+            Current schedule to perturb.
+
+        random_generator:
+            Source of randomness. If ``None``, a new generator is created.
+
+    Returns:
+        A valid neighbor schedule that prioritizes swaps on the critical
+        path, or a neighbor produced by an adjacent swap fallback when none
+        applies.
+    """
+    if random_generator is None:
+        random_generator = random.Random()
+
+    critical_path = schedule.critical_path()
+    possible_swaps: list[tuple[ScheduledOperation, ScheduledOperation]] = []
+    for i, current_scheduled_op in enumerate(critical_path[:-1]):
+        next_scheduled_op = critical_path[i + 1]
+        if current_scheduled_op.machine_id == next_scheduled_op.machine_id:
+            possible_swaps.append((current_scheduled_op, next_scheduled_op))
+
+    if not possible_swaps:
+        return swap_adjacent_operations(schedule, random_generator)
+
+    op1, op2 = random_generator.choice(possible_swaps)
+    job_sequences = schedule.job_sequences()
+    machine_id = op1.machine_id
+    idx1 = job_sequences[machine_id].index(op1.operation.job_id)
+    idx2 = job_sequences[machine_id].index(op2.operation.job_id)
+
+    job_sequences[machine_id][idx1], job_sequences[machine_id][idx2] = (
+        job_sequences[machine_id][idx2],
+        job_sequences[machine_id][idx1],
+    )
+    return Schedule.from_job_sequences(schedule.instance, job_sequences)

job_shop_lib/metaheuristics/_objective_functions.py

@@ -0,0 +1,73 @@
+from collections.abc import Callable
+from job_shop_lib import Schedule
+
+
+ObjectiveFunction = Callable[[Schedule], float]
+
+
+def get_makespan_with_penalties_objective(
+    deadline_penalty_factor: float = 1_000_000,
+    due_date_penalty_factor: float = 100,
+) -> ObjectiveFunction:
+    """Builds an objective function that returns the makespan plus penalties.
+
+    This factory returns a callable that evaluates a Schedule as the sum of
+    its makespan and penalties for violating operation-level deadlines and due
+    dates.
+
+    Penalties are applied per scheduled operation that finishes after its
+    corresponding attribute value:
+
+    - Deadline violation: adds ``deadline_penalty_factor`` once per violating
+      operation (hard constraint surrogate).
+    - Due date violation: adds ``due_date_penalty_factor`` once per violating
+      operation (soft constraint surrogate).
+
+    Args:
+        deadline_penalty_factor:
+            Cost added for each operation that
+            finishes after its deadline. Defaults to 1_000_000.
+        due_date_penalty_factor:
+            Cost added for each operation that
+            finishes after its due date. Defaults to 100.
+
+    Returns:
+        A function ``f(schedule) -> float`` that
+        computes ``schedule.makespan() + penalty``.
+
+    Notes:
+        - Deadlines and due dates are taken from each operation. If an
+          operation does not define the attribute (``None``), no penalty is
+          applied for that attribute.
+        - If the instance has neither deadlines nor due dates, the objective is
+          simply the makespan.
+    """
+
+    def objective(schedule: Schedule) -> float:
+        makespan = schedule.makespan()
+        instance = schedule.instance
+
+        # Fast path: no constraint attributes present in the instance
+        if not instance.has_deadlines and not instance.has_due_dates:
+            return makespan
+
+        penalty = 0.0
+        for machine_schedule in schedule.schedule:
+            for scheduled_op in machine_schedule:
+                op = scheduled_op.operation
+                # Deadline (hard) penalty
+                if (
+                    op.deadline is not None
+                    and scheduled_op.end_time > op.deadline
+                ):
+                    penalty += deadline_penalty_factor
+                # Due date (soft) penalty
+                if (
+                    op.due_date is not None
+                    and scheduled_op.end_time > op.due_date
+                ):
+                    penalty += due_date_penalty_factor
+
+        return makespan + penalty
+
+    return objective

job_shop_lib/metaheuristics/_simulated_annealing_solver.py

@@ -0,0 +1,163 @@
+from job_shop_lib import BaseSolver, JobShopInstance, Schedule
+from job_shop_lib.metaheuristics import JobShopAnnealer
+from job_shop_lib.dispatching.rules import DispatchingRuleSolver
+from job_shop_lib.metaheuristics import (
+    NeighborGenerator,
+    swap_in_critical_path,
+    ObjectiveFunction,
+)
+
+
+class SimulatedAnnealingSolver(BaseSolver):
+    """Wraps the :class:`JobShopAnnealer` to follow the
+    :class`~job_shop_lib.BaseSolver` interface.
+
+    .. seealso::
+        See the documentation of the :class:`JobShopAnnealer` class for more
+        details on the annealing process.
+
+    Attributes:
+        initial_temperature:
+            Initial temperature for the annealing process. It controls the
+            probability of accepting worse solutions. That sets the metropolis
+            criterion. Corresponds to the `tmax` parameter in the annealer.
+        ending_temperature:
+            Ending temperature for the annealing process. It controls when to
+            stop accepting worse solutions. Corresponds to the `tmin` parameter
+            in the annealer.
+        steps:
+            Number of steps to perform in the annealing process. This is the
+            number of iterations the algorithm will run.
+        updates:
+            The number of progress updates to print during the annealing
+            process. Set to 0 to disable updates.
+        seed:
+            Random seed for reproducibility. If ``None``, random behavior will
+            be non-deterministic.
+
+    Args:
+        initial_temperature:
+            Initial temperature for the annealing process. It controls the
+            probability of accepting worse solutions. That sets the metropolis
+            criterion. Corresponds to the `tmax` parameter in the annealer.
+        ending_temperature:
+            Ending temperature for the annealing process. It controls when to
+            stop accepting worse solutions. Corresponds to the `tmin` parameter
+            in the annealer.
+        steps:
+            Number of steps to perform in the annealing process. This is the
+            number of iterations the algorithm will run.
+        updates:
+            The number of progress updates to print during the annealing
+            process. Set to 0 to disable updates.
+        seed:
+            Random seed for reproducibility. If ``None``, random behavior will
+            be non-deterministic.
+    """
+
+    def __init__(
+        self,
+        *,
+        initial_temperature: float = 25000,
+        ending_temperature: float = 2.5,
+        steps: int = 50_000,
+        updates: int = 100,
+        objective_function: ObjectiveFunction | None = None,
+        seed: int | None = None,
+        neighbor_generator: NeighborGenerator = swap_in_critical_path,
+    ):
+        self.initial_temperature = initial_temperature
+        self.ending_temperature = ending_temperature
+        self.steps = steps
+        self.updates = updates
+        self.objective_function = objective_function
+        self.seed = seed
+        self.neighbor_generator = neighbor_generator
+        self.annealer_: JobShopAnnealer | None = None
+
+    def setup_annealer(
+        self, instance: JobShopInstance, initial_state: Schedule | None = None
+    ) -> None:
+        """Initializes the annealer with the given instance and initial state.
+
+        Args:
+            instance:
+                The job shop instance to solve.
+            initial_state:
+                Initial state of the schedule as a list of lists, where each
+                sublist represents the operations of a job.
+        """
+        if initial_state is None:
+            initial_state = self._generate_initial_state(instance)
+
+        annealer = JobShopAnnealer(
+            instance,
+            initial_state,
+            objective_function=self.objective_function,
+            seed=self.seed,
+            neighbor_generator=self.neighbor_generator,
+        )
+        best_hparams = {
+            "tmax": self.initial_temperature,
+            "tmin": self.ending_temperature,
+            "steps": self.steps,
+            "updates": self.updates,
+        }
+        annealer.set_schedule(best_hparams)
+        self.annealer_ = annealer
+
+    def solve(
+        self,
+        instance: JobShopInstance,
+        initial_state: Schedule | None = None,
+    ) -> Schedule:
+        """Solves the given Job Shop Scheduling problem using
+        simulated annealing.
+
+        Args:
+            instance:
+                The job shop problem instance to solve.
+            initial_state:
+                Initial job sequences for each machine. A job sequence is a
+                list of job ids. Each list of job ids represents the order of
+                operations on the machine. The machine that the list
+                corresponds to is determined by the index of the list. If
+                ``None``, the solver will generate an initial state using the
+                :class:`DispatchingRuleSolver`.
+
+        Returns:
+            The best schedule found.
+
+        """
+        self.setup_annealer(instance, initial_state)
+        # For type checking purposes, we assert that the annealer is set up.
+        assert (
+            self.annealer_ is not None
+        ), "There was a problem setting up the annealer."
+        try:
+            best_state, _ = self.annealer_.anneal()
+        except KeyboardInterrupt:
+            # If the annealing process is interrupted, we return the best state
+            # found so far.
+            best_state = self.annealer_.best_state
+        return best_state
+
+    @staticmethod
+    def _generate_initial_state(instance: JobShopInstance) -> Schedule:
+        """Uses the
+        :class:`~job_shop_lib.dispatching.rules.DispatchingRuleSolver` to
+        generate an initial state for the annealer.
+
+        .. note::
+            The first solution might be unfeasible if the job shop instance
+            has deadlines.
+
+        Args:
+            instance (JobShopInstance): The job shop problem instance.
+
+        Returns:
+            An initial schedule generated by the dispatching rule solver.
+        """
+        solver = DispatchingRuleSolver()
+        schedule = solver.solve(instance)
+        return schedule

{job_shop_lib-1.5.0.dist-info → job_shop_lib-1.6.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: job-shop-lib
-Version: 1.5.0
+Version: 1.6.0
 Summary: An easy-to-use and modular Python library for the Job Shop Scheduling Problem (JSSP)
 License: MIT
 Author: Pabloo22
@@ -21,6 +21,7 @@ Requires-Dist: ortools (>=9.9,<10.0) ; sys_platform != "darwin"
 Requires-Dist: ortools (>=9.9,<9.13) ; sys_platform == "darwin"
 Requires-Dist: pyarrow (>=15,<21)
 Requires-Dist: pygraphviz (>=1.12,<2.0) ; extra == "pygraphviz"
+Requires-Dist: simanneal (>=0.5.0,<0.6.0)
 Description-Content-Type: text/markdown
 
 <div align="center">
@@ -42,49 +43,34 @@ JobShopLib is a Python package for creating, solving, and visualizing job shop s
 
 It follows a modular design, allowing users to easily extend the library with new solvers, dispatching rules, visualization functions, etc.
 
-There is a [documentation page](https://job-shop-lib.readthedocs.io/en/stable/) for versions 1.0.0a3 and onward. See the [latest pull requests](https://github.com/Pabloo22/job_shop_lib/pulls?q=is%3Apr+is%3Aclosed) for the latest changes.
+We support multiple solvers, including:
+- **Constraint Programming**: Based on OR-Tools' CP-SAT solver. It supports **release dates, deadlines, and due dates.** See the ["Solving the Problem" tutorial](https://github.com/Pabloo22/job_shop_lib/blob/main/docs/source/tutorial/02-Solving-the-Problem.ipynb) for an example.
+- **Dispatching Rules**: A set of predefined rules and the ability to create custom ones. They support arbitrary **setup times, machine breakdowns, release dates, deadlines, and due dates**. See the [following example](https://github.com/Pabloo22/job_shop_lib/blob/main/docs/source/examples/03-Dispatching-Rules.ipynb). You can also create videos or GIFs of the scheduling process. For creating GIFs or videos, see the [Save Gif example](https://github.com/Pabloo22/job_shop_lib/blob/main/docs/source/examples/04-Save-Gif.ipynb).
+- **Metaheuristics**: Currently, we have a **simulated annealing** implementation that supports **release dates, deadlines, and due dates**. We also support arbitrary neighborhood search strategies, including swapping operations in the critical path as described in the paper "Job Shop Scheduling by Simulated Annealing" by van Laarhoven et al. (1992); and energy functions. See our [simulated annealing tutorial](https://github.com/Pabloo22/job_shop_lib/blob/main/docs/source/tutorial/03-Simulated-Annealing.ipynb).
+- **Reinforcement Learning**: Two Gymnasium environments for solving the problem with **graph neural networks** (GNNs) or any other method. The environments support **setup times, release dates, deadlines, and due dates.** We're currently building a tutorial on how to use them.
 
-See [`gnn_scheduler`](https://github.com/Pabloo22/gnn_scheduler/blob/main/gnn_scheduler/) for an example implementation of a graph neural network-based dispatcher trained with [PyTorch Geometric](https://pyg.org/).
-
-See [this](https://colab.research.google.com/drive/1XV_Rvq1F2ns6DFG8uNj66q_rcowwTZ4H?usp=sharing) Google Colab notebook for a quick start guide! More advanced examples can be found [here](https://job-shop-lib.readthedocs.io/en/stable/examples.html).
+We also provide useful utilities, data structures, and visualization functions:
+- **Intuitive Data Structures**: Easily create, manage, and manipulate job shop instances and solutions with user-friendly data structures. See [Getting Started](https://github.com/Pabloo22/job_shop_lib/blob/main/docs/source/tutorial/00-Getting-Started.ipynb) and [How Solutions are Represented](https://github.com/Pabloo22/job_shop_lib/blob/main/docs/source/tutorial/01-How-Solutions-are-Represented.ipynb).
+- **Benchmark Instances**: Load well-known benchmark instances directly from the library without manual downloading. See [Load Benchmark Instances](https://github.com/Pabloo22/job_shop_lib/blob/main/docs/source/examples/05-Load-Benchmark-Instances.ipynb).
+- **Random Instance Generation**: Create random instances with customizable sizes and properties. See [`generation`](https://job-shop-lib.readthedocs.io/en/stable/api/job_shop_lib.generation.html#module-job_shop_lib.generation) module.
+- **Gantt Charts**: Visualize final schedules and how they are created iteratively by dispatching rule solvers or sequences of scheduling decisions with GIFs or videos.
+- **Graph Representations**: Represent and visualize instances as disjunctive graphs or agent-task graphs (introduced in the ScheduleNet paper). Build your own custom graphs with the `JobShopGraph` class. See the [Disjunctive Graphs](https://github.com/Pabloo22/job_shop_lib/blob/main/docs/source/tutorial/04-Disjunctive-Graphs.ipynb) and [Resource Task Graphs](https://job-shop-lib.readthedocs.io/en/stable/examples/07-Resource-Task-Graph.html) examples.
 
 ## Installation :package:
 
 <!-- start installation -->
 
-JobShopLib is distributed on [PyPI](https://pypi.org/project/job-shop-lib/). You can install the latest stable version using `pip`:
-
 ```bash
 pip install job-shop-lib
 ```
 
-<!-- end installation -->
-
-<!-- key features -->
-
-## Key Features :star:
-
-- **Data Structures**: Easily create, manage, and manipulate job shop instances and solutions with user-friendly data structures. See [Getting Started](https://github.com/Pabloo22/job_shop_lib/blob/main/docs/source/tutorial/00-Getting-Started.ipynb) and [How Solutions are Represented](https://github.com/Pabloo22/job_shop_lib/blob/main/docs/source/tutorial/01-How-Solutions-are-Represented.ipynb).
-
-- **Benchmark Instances**: Load well-known benchmark instances directly from the library without manual downloading. See [Load Benchmark Instances](https://github.com/Pabloo22/job_shop_lib/blob/main/docs/source/examples/05-Load-Benchmark-Instances.ipynb).
-
-- **Random Instance Generation**: Create random instances with customizable sizes and properties. See [`generation`](job_shop_lib/generation) package.
-
-- **Multiple Solvers**:
-  - **Constraint Programming Solver**: OR-Tools' CP-SAT solver. See [Solving the Problem](https://github.com/Pabloo22/job_shop_lib/blob/main/docs/source/tutorial/02-Solving-the-Problem.ipynb).
-
-  - **Dispatching Rule Solvers**: Use any of the available dispatching rules or create custom ones. See [Dispatching Rules](https://github.com/Pabloo22/job_shop_lib/blob/main/docs/source/examples/03-Dispatching-Rules.ipynb).
-
-- **Gantt Charts**: Visualize final schedules and how are they created iteratively by dispatching rule solvers or sequences of scheduling decisions with GIFs or videos. See [Save Gif](https://github.com/Pabloo22/job_shop_lib/blob/main/docs/source/examples/06-Save-Gif.ipynb).
-
-- **Graph Representations**:
-  - **Disjunctive Graphs**: Represent and visualize instances as disjunctive graphs. See [Disjunctive Graph](https://github.com/Pabloo22/job_shop_lib/blob/main/docs/source/examples/04-Disjunctive-Graph.ipynb).
-  - **Agent-Task Graphs**: Encode instances as agent-task graphs (introduced in [ScheduleNet paper](https://arxiv.org/abs/2106.03051)). See [Agent-Task Graph](https://github.com/Pabloo22/job_shop_lib/blob/main/docs/source/examples/07-Agent-Task-Graph.ipynb).
-  - Build your own custom graphs with the `JobShopGraph` class.
+or 
 
-- **Gymnasium Environments**: Two environments for solving the problem with graph neural networks (GNNs) or any other method, and reinforcement learning (RL). See [SingleJobShopGraphEnv](https://github.com/Pabloo22/job_shop_lib/blob/main/docs/source/examples/09-SingleJobShopGraphEnv.ipynb) and [MultiJobShopGraphEnv](https://github.com/Pabloo22/job_shop_lib/blob/main/docs/source/examples/10-MultiJobShopGraphEnv.ipynb).
+```bash
+poetry add job-shop-lib
+```
 
-<!-- end key features -->
+<!-- end installation -->
 
 ## Publication :scroll:
 
@@ -219,6 +205,7 @@ A dispatching rule is a heuristic guideline used to prioritize and sequence jobs
 ```python
 class DispatchingRule(str, Enum):
     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_OPERATION_REMAINING = "most_operation_remaining"
@@ -432,6 +419,8 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 ## References :books:
 
+ - Peter J. M. van Laarhoven, Emile H. L. Aarts, Jan Karel Lenstra, (1992) Job Shop Scheduling by Simulated Annealing. Operations Research 40(1):113-125.
+
  - J. Adams, E. Balas, and D. Zawack, "The shifting bottleneck procedure
      for job shop scheduling," Management Science, vol. 34, no. 3,
      pp. 391–401, 1988.

{job_shop_lib-1.5.0.dist-info → job_shop_lib-1.6.0.dist-info}/RECORD

@@ -1,8 +1,8 @@
-job_shop_lib/__init__.py,sha256=vJ_HFv-mEpI6ejngfGDE4aTMgYvFR3kYm8nkFyGrMS8,639
-job_shop_lib/_base_solver.py,sha256=p17XmtufNc9Y481cqZUT45pEkUmmW1HWG53dfhIBJH8,1363
+job_shop_lib/__init__.py,sha256=7AD9gwI3xXZonyTg82RJ8dhTXg1QdRJpL3HA0Y7TElg,639
+job_shop_lib/_base_solver.py,sha256=8CCSiA2-DegCKRXhMw7yYyI8iPauTSuLku2LQ8dU-9U,1382
 job_shop_lib/_job_shop_instance.py,sha256=_92orxdi70645J7cQlRE1I0PebvpHRCP6958q9j2h18,24261
 job_shop_lib/_operation.py,sha256=JI5WjvRXNBeSpPOv3ZwSrUJ4jsVDJYKfMaDHYOaFYts,5945
-job_shop_lib/_schedule.py,sha256=3PgDZ-DZmlESh5TASNHTqW_8Z7XPVSF64knvXEGRIbM,12927
+job_shop_lib/_schedule.py,sha256=u0clgm2OTUsTstwd_AQeGQWANhmbWRrPPsKAc62iel4,17783
 job_shop_lib/_scheduled_operation.py,sha256=czrGr87EOTlO2NPolIN5CDigeiCzvQEyra5IZPwSFZc,2801
 job_shop_lib/benchmarking/__init__.py,sha256=JPnCw5mK7sADAW0HctVKHEDRw22afp9caNh2eUS36Ys,3290
 job_shop_lib/benchmarking/_load_benchmark.py,sha256=-cgyx0Kn6uAc3KdGFSQb6eUVQjQggmpVKOH9qusNkXI,2930
@@ -52,6 +52,11 @@ job_shop_lib/graphs/graph_updaters/_disjunctive_graph_updater.py,sha256=-t0T8W-J
 job_shop_lib/graphs/graph_updaters/_graph_updater.py,sha256=j1f7iWsa62GVszK2BPaMxnKBCEGWa9owm8g4VWUje8w,1967
 job_shop_lib/graphs/graph_updaters/_residual_graph_updater.py,sha256=9NG3pu7Z5h-ZTfX8rRiZbI_NfNQi80h-XUHainshjZY,6064
 job_shop_lib/graphs/graph_updaters/_utils.py,sha256=sdw2Vo75P9c6Fy-YBlfgpXb9gPwHUluTB1E-9WINm_g,730
+job_shop_lib/metaheuristics/__init__.py,sha256=z7bHN5vP-ctOSL0eUYK-aRyhRkU2lrDyA4kBs15EME0,1884
+job_shop_lib/metaheuristics/_job_shop_annealer.py,sha256=Ty4SLPZh1NrL-XRqU76EeN8fwUdKfqbphqfYEDje1lQ,9195
+job_shop_lib/metaheuristics/_neighbor_generators.py,sha256=3RePlnYvJdpdhObmf0m_3NhyUM7avfNr4vOZT0PWTRQ,6563
+job_shop_lib/metaheuristics/_objective_functions.py,sha256=GG5M3LoLnNzo1zxzfpNMvo4bdYlqWuhVA8mIkXFsxxM,2607
+job_shop_lib/metaheuristics/_simulated_annealing_solver.py,sha256=EMCrFl2zzJubrvCMi5upm8lnUgtBizhZbi4EvbnIsM4,6200
 job_shop_lib/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 job_shop_lib/reinforcement_learning/__init__.py,sha256=sAVgxylKfBnn2rrz0BFcab1kjvQQ1h-hgldfbkPF--E,1537
 job_shop_lib/reinforcement_learning/_multi_job_shop_graph_env.py,sha256=6nXw67Tfmim3LqlSuQ9Cfg3mMY-VmbMHuXfyOL90jng,15740
@@ -68,7 +73,7 @@ job_shop_lib/visualization/gantt/_plot_gantt_chart.py,sha256=_4UGUTRuIw0tLzsJD9G
 job_shop_lib/visualization/graphs/__init__.py,sha256=HUWzfgQLeklNROtjnxeJX_FIySo_baTXO6klx0zUVpQ,630
 job_shop_lib/visualization/graphs/_plot_disjunctive_graph.py,sha256=L9_ZGgvCFpGc2rTOdZESdtydFQqShjqedimIOhqZx6Y,16209
 job_shop_lib/visualization/graphs/_plot_resource_task_graph.py,sha256=nkkdZ-9_OBevw72Frecwzv1y3WyhGZ9r9lz0y9MXvZ8,13192
-job_shop_lib-1.5.0.dist-info/LICENSE,sha256=9mggivMGd5taAu3xbmBway-VQZMBzurBGHofFopvUsQ,1069
-job_shop_lib-1.5.0.dist-info/METADATA,sha256=ggq_EHjUpRr9jX_67Sc3Fhj7sFlOqOL1tWzqRY-4xzY,19130
-job_shop_lib-1.5.0.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
-job_shop_lib-1.5.0.dist-info/RECORD,,
+job_shop_lib-1.6.0.dist-info/LICENSE,sha256=9mggivMGd5taAu3xbmBway-VQZMBzurBGHofFopvUsQ,1069
+job_shop_lib-1.6.0.dist-info/METADATA,sha256=cDfJquD-2ph8c7Niv0_hZ_OGI_1fOmJLe-nNoXVS96s,19250
+job_shop_lib-1.6.0.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+job_shop_lib-1.6.0.dist-info/RECORD,,