job-shop-lib 1.5.0__tar.gz → 1.6.1__tar.gz

{job_shop_lib-1.5.0 → job_shop_lib-1.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: job-shop-lib
-Version: 1.5.0
+Version: 1.6.1
 Summary: An easy-to-use and modular Python library for the Job Shop Scheduling Problem (JSSP)
 License: MIT
 Author: Pabloo22
@@ -17,10 +17,10 @@ Requires-Dist: imageio[ffmpeg] (>=2.34.1,<3.0.0)
 Requires-Dist: matplotlib (>=3,<4)
 Requires-Dist: networkx (>=3,<4)
 Requires-Dist: numpy (>=1.26.4,<3.0.0)
-Requires-Dist: ortools (>=9.9,<10.0) ; sys_platform != "darwin"
-Requires-Dist: ortools (>=9.9,<9.13) ; sys_platform == "darwin"
+Requires-Dist: ortools (>=9.9,<9.13)
 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 +42,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 +204,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 +418,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 → job_shop_lib-1.6.1}/README.md

@@ -17,49 +17,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.
-
-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 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.
+
+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).
+or 
 
-- **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.
-
-- **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:
 
@@ -194,6 +179,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"
@@ -407,6 +393,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 → job_shop_lib-1.6.1}/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.1"
 
 __all__ = [
     "Operation",

{job_shop_lib-1.5.0 → job_shop_lib-1.6.1}/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-1.5.0 → job_shop_lib-1.6.1}/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,80 @@ 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
+
+        machine_op_index = {}
+        for machine_id, schedule_list in enumerate(self.schedule):
+            machine_op_index[machine_id] = {op: idx for idx, op in
+                                            enumerate(schedule_list)}
+
+        # 2. Trace backwards from the last operation
+        while True:
+            job_pred: ScheduledOperation | None = None
+            machine_pred: ScheduledOperation | None = 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_op_index
+                [current_scheduled_op.machine_id][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-1.6.1/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",
+]