job-shop-lib 1.0.0a1__tar.gz → 1.0.0a3__tar.gz

{job_shop_lib-1.0.0a1 → job_shop_lib-1.0.0a3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: job-shop-lib
-Version: 1.0.0a1
+Version: 1.0.0a3
 Summary: An easy-to-use and modular Python library for the Job Shop Scheduling Problem (JSSP)
 License: MIT
 Author: Pabloo22
@@ -29,6 +29,7 @@ Description-Content-Type: text/markdown
 <h1>JobShopLib</h1>
 
 [![Tests](https://github.com/Pabloo22/job_shop_lib/actions/workflows/tests.yaml/badge.svg)](https://github.com/Pabloo22/job_shop_lib/actions/workflows/tests.yaml)
+[![Documentation Status](https://readthedocs.org/projects/job-shop-lib/badge/?version=latest)](https://job-shop-lib.readthedocs.io/en/latest/?badge=latest)
 ![Python versions](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue)
 [![Black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -39,7 +40,7 @@ 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.
 
-See [this](https://colab.research.google.com/drive/1XV_Rvq1F2ns6DFG8uNj66q_rcowwTZ4H?usp=sharing) Google Colab notebook for a quick start guide! 
+See the [documentation](https://job-shop-lib.readthedocs.io/en/latest/) for more details about the latest version (1.0.0a2).
 
 ## Installation :package:
 
@@ -47,12 +48,23 @@ See [this](https://colab.research.google.com/drive/1XV_Rvq1F2ns6DFG8uNj66q_rcoww
 
 JobShopLib is distributed on [PyPI](https://pypi.org/project/job-shop-lib/) and it supports Python 3.10+.
 
-You can install the latest version using `pip`:
+You can install the latest stable version (version 0.5.1) using `pip`:
 
 ```bash
 pip install job-shop-lib
 ```
 
+See [this](https://colab.research.google.com/drive/1XV_Rvq1F2ns6DFG8uNj66q_rcowwTZ4H?usp=sharing) Google Colab notebook for a quick start guide! 
+
+
+Version 1.0.0 is currently in beta stage and can be installed with:
+
+```bash
+pip install job-shop-lib==1.0.0a3
+```
+
+Although this version is not stable and may contain breaking changes in subsequent releases, it is recommended to install it to access the new reinforcement learning environments and familiare yourself with new changes (see the [latest pull requests](https://github.com/Pabloo22/job_shop_lib/pulls?q=is%3Apr+is%3Aclosed)). This version is the first one with a [documentation page](https://job-shop-lib.readthedocs.io/en/latest/).
+
 <!-- end installation -->
 
 <!-- key features -->

{job_shop_lib-1.0.0a1 → job_shop_lib-1.0.0a3}/README.md

@@ -5,6 +5,7 @@
 <h1>JobShopLib</h1>
 
 [![Tests](https://github.com/Pabloo22/job_shop_lib/actions/workflows/tests.yaml/badge.svg)](https://github.com/Pabloo22/job_shop_lib/actions/workflows/tests.yaml)
+[![Documentation Status](https://readthedocs.org/projects/job-shop-lib/badge/?version=latest)](https://job-shop-lib.readthedocs.io/en/latest/?badge=latest)
 ![Python versions](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue)
 [![Black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -15,7 +16,7 @@ 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.
 
-See [this](https://colab.research.google.com/drive/1XV_Rvq1F2ns6DFG8uNj66q_rcowwTZ4H?usp=sharing) Google Colab notebook for a quick start guide! 
+See the [documentation](https://job-shop-lib.readthedocs.io/en/latest/) for more details about the latest version (1.0.0a2).
 
 ## Installation :package:
 
@@ -23,12 +24,23 @@ See [this](https://colab.research.google.com/drive/1XV_Rvq1F2ns6DFG8uNj66q_rcoww
 
 JobShopLib is distributed on [PyPI](https://pypi.org/project/job-shop-lib/) and it supports Python 3.10+.
 
-You can install the latest version using `pip`:
+You can install the latest stable version (version 0.5.1) using `pip`:
 
 ```bash
 pip install job-shop-lib
 ```
 
+See [this](https://colab.research.google.com/drive/1XV_Rvq1F2ns6DFG8uNj66q_rcowwTZ4H?usp=sharing) Google Colab notebook for a quick start guide! 
+
+
+Version 1.0.0 is currently in beta stage and can be installed with:
+
+```bash
+pip install job-shop-lib==1.0.0a3
+```
+
+Although this version is not stable and may contain breaking changes in subsequent releases, it is recommended to install it to access the new reinforcement learning environments and familiare yourself with new changes (see the [latest pull requests](https://github.com/Pabloo22/job_shop_lib/pulls?q=is%3Apr+is%3Aclosed)). This version is the first one with a [documentation page](https://job-shop-lib.readthedocs.io/en/latest/).
+
 <!-- end installation -->
 
 <!-- key features -->

{job_shop_lib-1.0.0a1 → job_shop_lib-1.0.0a3}/job_shop_lib/_job_shop_instance.py

@@ -20,15 +20,27 @@ class JobShopInstance:
     computations.
 
     Attributes:
-        jobs:
+        jobs (list[list[Operation]]):
             A list of lists of operations. Each list of operations represents
             a job, and the operations are ordered by their position in the job.
             The `job_id`, `position_in_job`, and `operation_id` attributes of
             the operations are set when the instance is created.
-        name:
+        name (str):
             A string with the name of the instance.
-        metadata:
+        metadata (dict[str, Any]):
             A dictionary with additional information about the instance.
+
+    Args:
+        jobs:
+            A list of lists of operations. Each list of operations
+            represents a job, and the operations are ordered by their
+            position in the job. The `job_id`, `position_in_job`, and
+            `operation_id` attributes of the operations are set when the
+            instance is created.
+        name:
+            A string with the name of the instance.
+        **metadata:
+            Additional information about the instance.
     """
 
     def __init__(
@@ -37,24 +49,10 @@ class JobShopInstance:
         name: str = "JobShopInstance",
         **metadata: Any,
     ):
-        """Initializes the instance based on a list of lists of operations.
-
-        Args:
-            jobs:
-                A list of lists of operations. Each list of operations
-                represents a job, and the operations are ordered by their
-                position in the job. The `job_id`, `position_in_job`, and
-                `operation_id` attributes of the operations are set when the
-                instance is created.
-            name:
-                A string with the name of the instance.
-            **metadata:
-                Additional information about the instance.
-        """
-        self.jobs = jobs
+        self.jobs: list[list[Operation]] = jobs
         self.set_operation_attributes()
-        self.name = name
-        self.metadata = metadata
+        self.name: str = name
+        self.metadata: dict[str, Any] = metadata
 
     def set_operation_attributes(self):
         """Sets the job_id and position of each operation."""

{job_shop_lib-1.0.0a1 → job_shop_lib-1.0.0a3}/job_shop_lib/_operation.py

@@ -23,32 +23,38 @@ class Operation:
         necessary to multiply all durations by a sufficiently large integer so
         that every duration is an integer.
 
-    Attributes:
-        machines: A list of machine ids that can perform the operation.
-        duration: The time it takes to perform the operation.
+    Args:
+        machines:
+            A list of machine ids that can perform the operation. If
+            only one machine can perform the operation, it can be passed as
+            an integer.
+        duration:
+            The time it takes to perform the operation.
     """
 
-    __slots__ = (
-        "machines",
-        "duration",
-        "job_id",
-        "position_in_job",
-        "operation_id",
-    )
+    __slots__ = {
+        "machines": (
+            "A list of machine ids that can perform the operation. If "
+            "only one machine can perform the operation, it can be passed as "
+            "an integer."
+        ),
+        "duration": (
+            "The time it takes to perform the operation. Often referred"
+            " to as the processing time."
+        ),
+        "job_id": "The id of the job the operation belongs to.",
+        "position_in_job": "The index of the operation in the job.",
+        "operation_id": (
+            "The id of the operation. This is unique within a "
+            ":class:`JobShopInstance`."
+        ),
+    }
 
     def __init__(self, machines: int | list[int], duration: int):
-        """Initializes the object with the given machines and duration.
-
-        Args:
-            machines:
-                A list of machine ids that can perform the operation. If
-                only one machine can perform the operation, it can be passed as
-                an integer.
-            duration:
-                The time it takes to perform the operation.
-        """
-        self.machines = [machines] if isinstance(machines, int) else machines
-        self.duration = duration
+        self.machines: list[int] = (
+            [machines] if isinstance(machines, int) else machines
+        )
+        self.duration: int = duration
 
         # Defined outside the class by the JobShopInstance class:
         self.job_id: int = -1
@@ -60,8 +66,8 @@ class Operation:
         """Returns the id of the machine associated with the operation.
 
         Raises:
-            UninitializedAttributeError: If the operation has multiple machines
-            in its list.
+            UninitializedAttributeError:
+                If the operation has multiple machines in its list.
         """
         if len(self.machines) > 1:
             raise UninitializedAttributeError(

{job_shop_lib-1.0.0a1 → job_shop_lib-1.0.0a3}/job_shop_lib/_schedule.py

@@ -25,27 +25,28 @@ class Schedule:
         is_complete
         add
         reset
-
-    Attributes:
-        instance:
-            The :class:`JobShopInstance` object that the schedule is for.
-        metadata:
-            A dictionary with additional information about the schedule. It
-            can be used to store information about the algorithm that generated
-            the schedule, for example.
     """
 
-    __slots__ = (
-        "instance",
-        "_schedule",
-        "metadata",
-    )
+    __slots__ = {
+        "instance": (
+            "The :class:`JobShopInstance` object that the schedule is for."
+        ),
+        "_schedule": (
+            "A list of lists of :class:`ScheduledOperation` objects. "
+            "Each list represents the order of operations on a machine."
+        ),
+        "metadata": (
+            "A dictionary with additional information about the "
+            "schedule. It can be used to store information about the "
+            "algorithm that generated the schedule, for example."
+        ),
+    }
 
     def __init__(
         self,
         instance: JobShopInstance,
         schedule: list[list[ScheduledOperation]] | None = None,
-        **metadata,
+        **metadata: Any,
     ):
         """Initializes the object with the given instance and schedule.
 
@@ -64,9 +65,9 @@ class Schedule:
 
         Schedule.check_schedule(schedule)
 
-        self.instance = instance
+        self.instance: JobShopInstance = instance
         self._schedule = schedule
-        self.metadata = metadata
+        self.metadata: dict[str, Any] = metadata
 
     def __repr__(self) -> str:
         return str(self.schedule)

{job_shop_lib-1.0.0a1 → job_shop_lib-1.0.0a3}/job_shop_lib/_scheduled_operation.py

@@ -5,17 +5,15 @@ from job_shop_lib.exceptions import ValidationError
 
 
 class ScheduledOperation:
-    """Data structure to store a scheduled operation.
+    """Data structure to store a scheduled operation."""
 
-    Attributes:
-        operation:
-            The :class:`Operation` object that is scheduled.
-        start_time:
-            The time at which the operation is scheduled to start.
-
-    """
-
-    __slots__ = ("operation", "start_time", "_machine_id")
+    __slots__ = {
+        "operation": "The :class:`Operation` object that is scheduled.",
+        "start_time": "The time at which the operation is scheduled to start.",
+        "_machine_id": (
+            "The id of the machine on which the operation is scheduled."
+        ),
+    }
 
     def __init__(self, operation: Operation, start_time: int, machine_id: int):
         """Initializes a new instance of the :class:`ScheduledOperation` class.
@@ -33,8 +31,8 @@ class ScheduledOperation:
                 If the given machine_id is not in the list of valid machines
                 for the operation.
         """
-        self.operation = operation
-        self.start_time = start_time
+        self.operation: Operation = operation
+        self.start_time: int = start_time
         self._machine_id = machine_id
         self.machine_id = machine_id  # Validate machine_id
 

{job_shop_lib-1.0.0a1 → job_shop_lib-1.0.0a3}/job_shop_lib/constraint_programming/_ortools_solver.py

@@ -22,22 +22,32 @@ class ORToolsSolver(BaseSolver):
     <https://developers.google.com/optimization/cp/cp_solver>`_ solver.
 
     Attributes:
-        log_search_progress (``bool``):
+        log_search_progress (bool):
             Whether to log the search progress to the console.
-        max_time_in_seconds (``float | None``):
+        max_time_in_seconds (float | None):
             The maximum time in seconds to allow the solver to search for
             a solution. If no solution is found within this time, a
             :class:`~job_shop_lib.exceptions.NoSolutionFoundError` is
             raised. If ``None``, the solver will run until an optimal
             solution is found.
-        model (``cp_model.CpModel``):
+        model (cp_model.CpModel):
             The `OR-Tools' CP-SAT model
             <https://developers.google.com/optimization/reference/python/sat/
             python/cp_model#cp_model.CpModel>`_.
-        solver (``cp_model.CpSolver``):
+        solver (cp_model.CpSolver):
             The `OR-Tools' CP-SAT solver
             <https://developers.google.com/optimization/reference/python/sat/
             python/cp_model#cp_model.CpSolver>`_.
+
+    Args:
+        max_time_in_seconds:
+            The maximum time in seconds to allow the solver to search for
+            a solution. If no solution is found within this time, a
+            :class:`~job_shop_lib.exceptions.NoSolutionFoundError` is
+            raised. If ``None``, the solver will run until an optimal
+            solution is found.
+        log_search_progress:
+            Whether to log the search progress to the console.
     """
 
     def __init__(
@@ -45,18 +55,6 @@ class ORToolsSolver(BaseSolver):
         max_time_in_seconds: float | None = None,
         log_search_progress: bool = False,
     ):
-        """Initializes the solver.
-
-        Args:
-            max_time_in_seconds:
-                The maximum time in seconds to allow the solver to search for
-                a solution. If no solution is found within this time, a
-                :class:`~job_shop_lib.exceptions.NoSolutionFoundError` is
-                raised. If ``None``, the solver will run until an optimal
-                solution is found.
-            log_search_progress:
-                Whether to log the search progress to the console.
-        """
         self.log_search_progress = log_search_progress
         self.max_time_in_seconds = max_time_in_seconds
 
@@ -66,6 +64,23 @@ class ORToolsSolver(BaseSolver):
         self._operations_start: dict[Operation, tuple[IntVar, IntVar]] = {}
 
     def __call__(self, instance: JobShopInstance) -> Schedule:
+        """Equivalent to calling the :meth:`~ORToolsSolver.solve` method.
+
+        This method is necessary because, in JobShopLib, solvers are defined
+        as callables that receive an instance and return a schedule.
+
+        Args:
+            instance: The job shop instance to be solved.
+
+        Returns:
+            The best schedule found by the solver.
+            Its metadata contains the following information:
+
+            * status (``str``): ``"optimal"`` or ``"feasible"``
+            * elapsed_time (``float``): The time taken to solve the problem
+            * makespan (``int``): The total duration of the schedule
+            * solved_by (``str``): ``"ORToolsSolver"``
+        """
         # Re-defined here since we already add metadata to the schedule in
         # the solve method.
         return self.solve(instance)

{job_shop_lib-1.0.0a1 → job_shop_lib-1.0.0a3}/job_shop_lib/dispatching/__init__.py

@@ -32,6 +32,8 @@ from ._ready_operation_filters import (
     filter_dominated_operations,
     filter_non_immediate_machines,
     ReadyOperationsFilter,
+    filter_non_idle_machines,
+    filter_non_immediate_operations,
 )
 from ._dispatcher_observer_config import DispatcherObserverConfig
 from ._factories import (
@@ -53,4 +55,6 @@ __all__ = [
     "DispatcherObserverConfig",
     "UnscheduledOperationsObserver",
     "ReadyOperationsFilter",
+    "filter_non_idle_machines",
+    "filter_non_immediate_operations",
 ]

{job_shop_lib-1.0.0a1 → job_shop_lib-1.0.0a3}/job_shop_lib/dispatching/_dispatcher.py

@@ -156,26 +156,30 @@ class Dispatcher:
     responsible for scheduling the operations on the machines and keeping
     track of the next available time for each machine and job.
 
-    Attributes:
+    Args:
         instance:
-            The instance of the job shop problem to be scheduled.
-        schedule:
-            The schedule of operations on machines.
+            The instance of the job shop problem to be solved.
         ready_operations_filter:
-            A function that filters out operations that are not ready to be
-            scheduled.
+            A function that filters out operations that are not ready to
+            be scheduled. The function should take the dispatcher and a
+            list of operations as input and return a list of operations
+            that are ready to be scheduled. If ``None``, no filtering is
+            done.
     """
 
-    __slots__ = (
-        "instance",
-        "schedule",
-        "_machine_next_available_time",
-        "_job_next_operation_index",
-        "_job_next_available_time",
-        "ready_operations_filter",
-        "subscribers",
-        "_cache",
-    )
+    __slots__ = {
+        "instance": "The instance of the job shop problem to be scheduled.",
+        "schedule": "The schedule of operations on machines.",
+        "_machine_next_available_time": "",
+        "_job_next_operation_index": "",
+        "_job_next_available_time": "",
+        "ready_operations_filter": (
+            "A function that filters out operations that are not ready to be "
+            "scheduled."
+        ),
+        "subscribers": "A list of observers subscribed to the dispatcher.",
+        "_cache": "A dictionary to cache the results of the cached methods.",
+    }
 
     def __init__(
         self,
@@ -184,18 +188,6 @@ class Dispatcher:
             Callable[[Dispatcher, list[Operation]], list[Operation]] | None
         ) = None,
     ) -> None:
-        """Initializes the object with the given instance.
-
-        Args:
-            instance:
-                The instance of the job shop problem to be solved.
-            ready_operations_filter:
-                A function that filters out operations that are not ready to
-                be scheduled. The function should take the dispatcher and a
-                list of operations as input and return a list of operations
-                that are ready to be scheduled. If ``None``, no filtering is
-                done.
-        """
 
         self.instance = instance
         self.schedule = Schedule(self.instance)
@@ -371,7 +363,7 @@ class Dispatcher:
         The current time is the minimum start time of the available
         operations.
         """
-        available_operations = self.ready_operations()
+        available_operations = self.available_operations()
         current_time = self.min_start_time(available_operations)
         return current_time
 
@@ -387,7 +379,7 @@ class Dispatcher:
         return int(min_start_time)
 
     @_dispatcher_cache
-    def ready_operations(self) -> list[Operation]:
+    def available_operations(self) -> list[Operation]:
         """Returns a list of available operations for processing, optionally
         filtering out operations using the filter function.
 
@@ -443,7 +435,7 @@ class Dispatcher:
     @_dispatcher_cache
     def available_machines(self) -> list[int]:
         """Returns the list of ready machines."""
-        available_operations = self.ready_operations()
+        available_operations = self.available_operations()
         available_machines = set()
         for operation in available_operations:
             available_machines.update(operation.machines)
@@ -452,7 +444,7 @@ class Dispatcher:
     @_dispatcher_cache
     def available_jobs(self) -> list[int]:
         """Returns the list of ready jobs."""
-        available_operations = self.ready_operations()
+        available_operations = self.available_operations()
         available_jobs = set(
             operation.job_id for operation in available_operations
         )

{job_shop_lib-1.0.0a1 → job_shop_lib-1.0.0a3}/job_shop_lib/dispatching/_factories.py

@@ -13,6 +13,8 @@ from job_shop_lib.dispatching import (
     Dispatcher,
     filter_dominated_operations,
     filter_non_immediate_machines,
+    filter_non_idle_machines,
+    filter_non_immediate_operations,
     ReadyOperationsFilter,
 )
 
@@ -27,6 +29,8 @@ class ReadyOperationsFilterType(str, Enum):
 
     DOMINATED_OPERATIONS = "dominated_operations"
     NON_IMMEDIATE_MACHINES = "non_immediate_machines"
+    NON_IDLE_MACHINES = "non_idle_machines"
+    NON_IMMEDIATE_OPERATIONS = "non_immediate_operations"
 
 
 def create_composite_operation_filter(
@@ -114,6 +118,10 @@ def ready_operations_filter_factory(
         ReadyOperationsFilterType.NON_IMMEDIATE_MACHINES: (
             filter_non_immediate_machines
         ),
+        ReadyOperationsFilterType.NON_IDLE_MACHINES: filter_non_idle_machines,
+        ReadyOperationsFilterType.NON_IMMEDIATE_OPERATIONS: (
+            filter_non_immediate_operations
+        ),
     }
 
     if filter_name not in filtering_strategies:

{job_shop_lib-1.0.0a1 → job_shop_lib-1.0.0a3}/job_shop_lib/dispatching/_ready_operation_filters.py

@@ -15,6 +15,86 @@ ReadyOperationsFilter = Callable[
 ]
 
 
+def filter_non_idle_machines(
+    dispatcher: Dispatcher, operations: list[Operation]
+) -> list[Operation]:
+    """Filters out all the operations associated with non-idle machines.
+
+    A machine is considered idle if there are no ongoing operations
+    currently scheduled on it. This filter removes operations that are
+    associated with machines that are busy (i.e., have at least one
+    uncompleted operation).
+
+    Utilizes :meth:``Dispatcher.ongoing_operations()`` to determine machine
+    statuses.
+
+    Args:
+        dispatcher: The dispatcher object.
+        operations: The list of operations to filter.
+
+    Returns:
+        The list of operations that are associated with idle machines.
+    """
+    current_time = dispatcher.min_start_time(operations)
+    non_idle_machines = _get_non_idle_machines(dispatcher, current_time)
+
+    # Filter operations to keep those that are associated with at least one
+    # idle machine
+    filtered_operations: list[Operation] = []
+    for operation in operations:
+        if all(
+            machine_id in non_idle_machines
+            for machine_id in operation.machines
+        ):
+            continue
+        filtered_operations.append(operation)
+
+    return filtered_operations
+
+
+def _get_non_idle_machines(
+    dispatcher: Dispatcher, current_time: int
+) -> set[int]:
+    """Returns the set of machine ids that are currently busy (i.e., have at
+    least one uncompleted operation)."""
+
+    non_idle_machines = set()
+    for machine_schedule in dispatcher.schedule.schedule:
+        for scheduled_operation in reversed(machine_schedule):
+            is_completed = scheduled_operation.end_time <= current_time
+            if is_completed:
+                break
+            non_idle_machines.add(scheduled_operation.machine_id)
+
+    return non_idle_machines
+
+
+def filter_non_immediate_operations(
+    dispatcher: Dispatcher, operations: list[Operation]
+) -> list[Operation]:
+    """Filters out all the operations that can't start immediately.
+
+    An operation can start immediately if its earliest start time is the
+    current time.
+
+    The current time is determined by the minimum start time of the
+    operations.
+
+    Args:
+        dispatcher: The dispatcher object.
+        operations: The list of operations to filter.
+    """
+
+    min_start_time = dispatcher.min_start_time(operations)
+    immediate_operations: list[Operation] = []
+    for operation in operations:
+        start_time = dispatcher.earliest_start_time(operation)
+        if start_time == min_start_time:
+            immediate_operations.append(operation)
+
+    return immediate_operations
+
+
 def filter_dominated_operations(
     dispatcher: Dispatcher, operations: list[Operation]
 ) -> list[Operation]: