job-shop-lib 1.3.0__tar.gz → 1.6.0__tar.gz

{job_shop_lib-1.3.0 → job_shop_lib-1.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: job-shop-lib
-Version: 1.3.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.3.0 → job_shop_lib-1.6.0}/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.3.0 → job_shop_lib-1.6.0}/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.3.0"
+__version__ = "1.6.0"
 
 __all__ = [
     "Operation",

{job_shop_lib-1.3.0 → job_shop_lib-1.6.0}/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.3.0 → job_shop_lib-1.6.0}/job_shop_lib/_job_shop_instance.py

@@ -3,8 +3,10 @@
 from __future__ import annotations
 
 import os
+from collections.abc import Sequence
 import functools
 from typing import Any
+import warnings
 
 import numpy as np
 from numpy.typing import NDArray
@@ -40,6 +42,9 @@ class JobShopInstance:
         is_flexible
         durations_matrix
         machines_matrix
+        release_dates_matrix
+        deadlines_matrix
+        due_dates_matrix
         durations_matrix_array
         machines_matrix_array
         operations_by_machine
@@ -92,6 +97,24 @@ class JobShopInstance:
         self.name: str = name
         self.metadata: dict[str, Any] = metadata
 
+        deprecated_keys = {
+            "release_dates_matrix",
+            "deadlines_matrix",
+            "due_dates_matrix",
+        }
+        if any(key in self.metadata for key in deprecated_keys):
+            warnings.warn(
+                "The use of 'release_dates_matrix', 'deadlines_matrix', or "
+                "'due_dates_matrix' in metadata is deprecated."
+                "Please add these attributes "
+                "directly to the Operation class. Not doing so may cause bugs "
+                "when using the dispatching module.You can use the "
+                "`JobShopInstance.from_matrices` method to create an "
+                "instance from 2D sequences. ",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
     def set_operation_attributes(self):
         """Sets the ``job_id``, ``position_in_job``, and ``operation_id``
         attributes for each operation in the instance.
@@ -196,14 +219,25 @@ class JobShopInstance:
                     "duration_matrix": self.durations_matrix,
                     "machines_matrix": self.machines_matrix,
                     "metadata": self.metadata,
+                    # Optionally (if the instance has them):
+                    "release_dates_matrix": self.release_dates_matrix,
+                    "deadlines_matrix": self.deadlines_matrix,
+                    "due_dates_matrix": self.due_dates_matrix,
                 }
         """
-        return {
+        data = {
             "name": self.name,
             "duration_matrix": self.durations_matrix,
             "machines_matrix": self.machines_matrix,
             "metadata": self.metadata,
         }
+        if self.has_release_dates:
+            data["release_dates_matrix"] = self.release_dates_matrix
+        if self.has_deadlines:
+            data["deadlines_matrix"] = self.deadlines_matrix
+        if self.has_due_dates:
+            data["due_dates_matrix"] = self.due_dates_matrix
+        return data
 
     @classmethod
     def from_matrices(
@@ -212,6 +246,9 @@ class JobShopInstance:
         machines_matrix: list[list[list[int]]] | list[list[int]],
         name: str = "JobShopInstance",
         metadata: dict[str, Any] | None = None,
+        release_dates_matrix: list[list[int]] | None = None,
+        deadlines_matrix: list[list[int | None]] | None = None,
+        due_dates_matrix: list[list[int | None]] | None = None,
     ) -> JobShopInstance:
         """Creates a :class:`JobShopInstance` from duration and machines
         matrices.
@@ -219,16 +256,26 @@ class JobShopInstance:
         Args:
             duration_matrix:
                 A list of lists of integers. The i-th list contains the
-                durations of the operations of the job with id i.
+                durations of the operations of the job with id ``i``.
             machines_matrix:
                 A list of lists of lists of integers if the
                 instance is flexible, or a list of lists of integers if the
                 instance is not flexible. The i-th list contains the machines
-                in which the operations of the job with id i can be processed.
+                in which the operations of the job with id ``i`` can be
+                processed.
             name:
                 A string with the name of the instance.
             metadata:
                 A dictionary with additional information about the instance.
+            release_dates_matrix:
+                A list of lists of integers. The i-th list contains the
+                release dates of the operations of the job with id ``i``.
+            deadlines_matrix:
+                A list of lists of optional integers. The i-th list contains
+                the deadlines of the operations of the job with id ``i``.
+            due_dates_matrix:
+                A list of lists of optional integers. The i-th list contains
+                the due dates of the operations of the job with id ``i``.
 
         Returns:
             A :class:`JobShopInstance` object.
@@ -241,8 +288,29 @@ class JobShopInstance:
             for position_in_job in range(num_operations):
                 duration = duration_matrix[job_id][position_in_job]
                 machines = machines_matrix[job_id][position_in_job]
+                release_date = (
+                    release_dates_matrix[job_id][position_in_job]
+                    if release_dates_matrix
+                    else 0
+                )
+                deadline = (
+                    deadlines_matrix[job_id][position_in_job]
+                    if deadlines_matrix
+                    else None
+                )
+                due_date = (
+                    due_dates_matrix[job_id][position_in_job]
+                    if due_dates_matrix
+                    else None
+                )
                 jobs[job_id].append(
-                    Operation(duration=duration, machines=machines)
+                    Operation(
+                        duration=duration,
+                        machines=machines,
+                        release_date=release_date,
+                        deadline=deadline,
+                        due_date=due_date,
+                    )
                 )
 
         metadata = {} if metadata is None else metadata
@@ -289,6 +357,21 @@ class JobShopInstance:
             for job in self.jobs
         )
 
+    @functools.cached_property
+    def has_release_dates(self) -> bool:
+        """Returns ``True`` if any operation has a release date > 0."""
+        return any(op.release_date > 0 for job in self.jobs for op in job)
+
+    @functools.cached_property
+    def has_deadlines(self) -> bool:
+        """Returns ``True`` if any operation has a deadline."""
+        return any(op.deadline is not None for job in self.jobs for op in job)
+
+    @functools.cached_property
+    def has_due_dates(self) -> bool:
+        """Returns ``True`` if any operation has a due date."""
+        return any(op.due_date is not None for job in self.jobs for op in job)
+
     @functools.cached_property
     def durations_matrix(self) -> list[list[int]]:
         """Returns the duration matrix of the instance.
@@ -330,23 +413,75 @@ class JobShopInstance:
             [operation.machine_id for operation in job] for job in self.jobs
         ]
 
+    @functools.cached_property
+    def release_dates_matrix(self) -> list[list[int]]:
+        """Returns the release dates matrix of the instance.
+
+        The release date of the operation with ``job_id`` i and
+        ``position_in_job`` j is stored in the i-th position of the j-th list
+        of the returned matrix.
+        """
+        return [
+            [operation.release_date for operation in job] for job in self.jobs
+        ]
+
+    @functools.cached_property
+    def deadlines_matrix(self) -> list[list[int | None]]:
+        """Returns the deadlines matrix of the instance.
+
+        The deadline of the operation with ``job_id`` i and
+        ``position_in_job`` j is stored in the i-th position of the j-th list
+        of the returned matrix.
+        """
+        return [[operation.deadline for operation in job] for job in self.jobs]
+
+    @functools.cached_property
+    def due_dates_matrix(self) -> list[list[int | None]]:
+        """Returns the due dates matrix of the instance.
+
+        The due date of the operation with ``job_id`` i and
+        ``position_in_job`` j is stored in the i-th position of the j-th list
+        of the returned matrix.
+        """
+        return [[operation.due_date for operation in job] for job in self.jobs]
+
     @functools.cached_property
     def durations_matrix_array(self) -> NDArray[np.float32]:
         """Returns the duration matrix of the instance as a numpy array.
 
-        The returned array has shape (``num_jobs``,
-        ``max_num_operations_per_job``).
-        Non-existing operations are filled with ``np.nan``.
+        If the jobs have different number of operations, the matrix is
+        padded with ``np.nan`` to make it rectangular.
+        """
+        return self._fill_matrix_with_nans_2d(self.durations_matrix)
 
-        Example:
-            >>> jobs = [[Operation(0, 2), Operation(1, 3)], [Operation(0, 4)]]
-            >>> instance = JobShopInstance(jobs)
-            >>> instance.durations_matrix_array
-            array([[ 2.,  3.],
-                   [ 4., nan]], dtype=float32)
+    @functools.cached_property
+    def release_dates_matrix_array(self) -> NDArray[np.float32]:
+        """Returns the release dates matrix of the instance as a numpy array.
+
+        If the jobs have different number of operations, the matrix is
+        padded with ``np.nan`` to make it rectangular.
         """
-        duration_matrix = self.durations_matrix
-        return self._fill_matrix_with_nans_2d(duration_matrix)
+        return self._fill_matrix_with_nans_2d(self.release_dates_matrix)
+
+    @functools.cached_property
+    def deadlines_matrix_array(self) -> NDArray[np.float32]:
+        """Returns the deadlines matrix of the instance as a numpy array.
+
+        If the jobs have different number of operations, the matrix is
+        padded with ``np.nan`` to make it rectangular. None values are also
+        converted to ``np.nan``.
+        """
+        return self._fill_matrix_with_nans_2d(self.deadlines_matrix)
+
+    @functools.cached_property
+    def due_dates_matrix_array(self) -> NDArray[np.float32]:
+        """Returns the due dates matrix of the instance as a numpy array.
+
+        If the jobs have different number of operations, the matrix is
+        padded with ``np.nan`` to make it rectangular. None values are also
+        converted to ``np.nan``.
+        """
+        return self._fill_matrix_with_nans_2d(self.due_dates_matrix)
 
     @functools.cached_property
     def machines_matrix_array(self) -> NDArray[np.float32]:
@@ -474,13 +609,13 @@ class JobShopInstance:
 
     @staticmethod
     def _fill_matrix_with_nans_2d(
-        matrix: list[list[int]],
+        matrix: Sequence[Sequence[int | None]],
     ) -> NDArray[np.float32]:
-        """Fills a matrix with ``np.nan`` values.
+        """Creates a 2D numpy array padded with ``np.nan`` values.
 
         Args:
             matrix:
-                A list of lists of integers.
+                A list of lists of integers or Nones.
 
         Returns:
             A numpy array with the same shape as the input matrix, filled with
@@ -491,14 +626,17 @@ class JobShopInstance:
             (len(matrix), max_length), np.nan, dtype=np.float32
         )
         for i, row in enumerate(matrix):
-            squared_matrix[i, : len(row)] = row
+            processed_row = [
+                item if item is not None else np.nan for item in row
+            ]
+            squared_matrix[i, : len(processed_row)] = processed_row
         return squared_matrix
 
     @staticmethod
     def _fill_matrix_with_nans_3d(
         matrix: list[list[list[int]]],
     ) -> NDArray[np.float32]:
-        """Fills a 3D matrix with ``np.nan`` values.
+        """Creates a 3D numpy array padded with ``np.nan`` values.
 
         Args:
             matrix:
@@ -522,9 +660,3 @@ class JobShopInstance:
             for j, inner_row in enumerate(row):
                 squared_matrix[i, j, : len(inner_row)] = inner_row
         return squared_matrix
-
-
-if __name__ == "__main__":
-    import doctest
-
-    doctest.testmod()

{job_shop_lib-1.3.0 → job_shop_lib-1.6.0}/job_shop_lib/_operation.py

@@ -30,6 +30,16 @@ class Operation:
             an integer.
         duration:
             The time it takes to perform the operation.
+        release_date:
+            The earliest moment this operation can be scheduled to start.
+            Defaults to ``0``.
+        deadline:
+            A hard cutoff time by which the job must be finished. A schedule
+            is invalid if the job completes after this time. Defaults to
+            ``None``.
+        due_date:
+            The target completion time for the job. Finishing late is allowed
+            but incurs a penalty (e.g., tardiness). Defaults to ``None``.
     """
 
     __slots__ = {
@@ -42,6 +52,20 @@ class Operation:
             "The time it takes to perform the operation. Often referred"
             " to as the processing time."
         ),
+        "release_date": (
+            "The earliest moment this operation can be scheduled to start. "
+            "Defaults to ``0``."
+        ),
+        "deadline": (
+            "A hard cutoff time by which the job must be finished. A schedule "
+            "is invalid if the job completes after this time. Defaults to "
+            "``None``."
+        ),
+        "due_date": (
+            "The target completion time for the job. Finishing late is "
+            "allowed but incurs a penalty (e.g., tardiness). Defaults to "
+            "``None``."
+        ),
         "job_id": (
             "The id of the job the operation belongs to. Defaults to -1. "
             "It is usually set by the :class:`JobShopInstance` class after "
@@ -59,11 +83,21 @@ class Operation:
         ),
     }
 
-    def __init__(self, machines: int | list[int], duration: int):
+    def __init__(
+        self,
+        machines: int | list[int],
+        duration: int,
+        release_date: int = 0,
+        deadline: int | None = None,
+        due_date: int | None = None,
+    ):
         self.machines: list[int] = (
             [machines] if isinstance(machines, int) else machines
         )
         self.duration: int = duration
+        self.release_date: int = release_date
+        self.deadline: int | None = deadline
+        self.due_date: int | None = due_date
 
         # Defined outside the class by the JobShopInstance class:
         self.job_id: int = -1
@@ -93,9 +127,9 @@ class Operation:
     def is_initialized(self) -> bool:
         """Returns whether the operation has been initialized."""
         return (
-            self.job_id == -1
-            or self.position_in_job == -1
-            or self.operation_id == -1
+            self.job_id != -1
+            and self.position_in_job != -1
+            and self.operation_id != -1
         )
 
     def __hash__(self) -> int:
@@ -104,7 +138,16 @@ class Operation:
     def __eq__(self, value: object) -> bool:
         if not isinstance(value, Operation):
             return False
-        return self.__slots__ == value.__slots__
+        return (
+            self.machines == value.machines
+            and self.duration == value.duration
+            and self.release_date == value.release_date
+            and self.deadline == value.deadline
+            and self.due_date == value.due_date
+            and self.job_id == value.job_id
+            and self.position_in_job == value.position_in_job
+            and self.operation_id == value.operation_id
+        )
 
     def __repr__(self) -> str:
         machines = (