job-shop-lib 1.0.0a2__py3-none-any.whl → 1.0.0a4__py3-none-any.whl

job_shop_lib/_job_shop_instance.py

@@ -15,49 +15,105 @@ from job_shop_lib import Operation
 class JobShopInstance:
     """Data structure to store a Job Shop Scheduling Problem instance.
 
-    Additional attributes such as `num_jobs` or `num_machines` can be computed
-    from the instance and are cached for performance if they require expensive
-    computations.
+    Additional attributes such as ``num_machines`` or ``durations_matrix`` can
+    be computed from the instance and are cached for performance if they
+    require expensive computations.
+
+    Methods:
+
+    .. autosummary::
+        :nosignatures:
+
+        from_taillard_file
+        to_dict
+        from_matrices
+        set_operation_attributes
+
+    Properties:
+
+    .. autosummary::
+        :nosignatures:
+
+        num_jobs
+        num_machines
+        num_operations
+        is_flexible
+        durations_matrix
+        machines_matrix
+        durations_matrix_array
+        machines_matrix_array
+        operations_by_machine
+        max_duration
+        max_duration_per_job
+        max_duration_per_machine
+        job_durations
+        machine_loads
+        total_duration
 
     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:
+            The ``job_id``, ``position_in_job``, and `operation_id` attributes
+            of the operations are set when the instance is created.
+        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.
+        set_operation_attributes:
+            If True, the ``job_id``, ``position_in_job``, and ``operation_id``
+            attributes of the operations are set when the instance is created.
+            See :meth:`set_operation_attributes` for more information. Defaults
+            to True.
+        **metadata:
+            Additional information about the instance.
     """
 
     def __init__(
         self,
         jobs: list[list[Operation]],
         name: str = "JobShopInstance",
+        set_operation_attributes: bool = True,
         **metadata: Any,
     ):
-        """Initializes the instance based on a list of lists of operations.
+        self.jobs: list[list[Operation]] = jobs
+        if set_operation_attributes:
+            self.set_operation_attributes()
+        self.name: str = name
+        self.metadata: dict[str, Any] = metadata
+
+    def set_operation_attributes(self):
+        """Sets the ``job_id``, ``position_in_job``, and ``operation_id``
+        attributes for each operation in the instance.
+
+        The ``job_id`` attribute is set to the id of the job to which the
+        operation belongs.
+
+        The ``position_in_job`` attribute is set to the
+        position of the operation in the job (starts from 0).
+
+        The ``operation_id`` attribute is set to a unique identifier for the
+        operation (starting from 0).
+
+        The formula to compute the ``operation_id`` in a job shop instance with
+        a fixed number of operations per job is:
+
+        .. code-block:: python
+
+            operation_id = job_id * num_operations_per_job + position_in_job
 
-        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.set_operation_attributes()
-        self.name = name
-        self.metadata = metadata
 
-    def set_operation_attributes(self):
-        """Sets the job_id and position of each operation."""
         operation_id = 0
         for job_id, job in enumerate(self.jobs):
             for position, operation in enumerate(job):
@@ -92,8 +148,8 @@ class JobShopInstance:
                 Additional information about the instance.
 
         Returns:
-            A JobShopInstance object with the operations read from the file,
-            and the name and metadata provided.
+            A :class:`JobShopInstance` object with the operations read from the
+            file, and the name and metadata provided.
         """
         with open(file_path, "r", encoding=encoding) as file:
             lines = file.readlines()
@@ -130,13 +186,17 @@ class JobShopInstance:
         like Taillard's.
 
         Returns:
-        The returned dictionary has the following structure:
-        {
-            "name": self.name,
-            "duration_matrix": self.durations_matrix,
-            "machines_matrix": self.machines_matrix,
-            "metadata": self.metadata,
-        }
+            dict[str, Any]: The returned dictionary has the following
+            structure:
+
+            .. code-block:: python
+
+                {
+                    "name": self.name,
+                    "duration_matrix": self.durations_matrix,
+                    "machines_matrix": self.machines_matrix,
+                    "metadata": self.metadata,
+                }
         """
         return {
             "name": self.name,
@@ -153,7 +213,8 @@ class JobShopInstance:
         name: str = "JobShopInstance",
         metadata: dict[str, Any] | None = None,
     ) -> JobShopInstance:
-        """Creates a JobShopInstance from duration and machines matrices.
+        """Creates a :class:`JobShopInstance` from duration and machines
+        matrices.
 
         Args:
             duration_matrix:
@@ -170,7 +231,7 @@ class JobShopInstance:
                 A dictionary with additional information about the instance.
 
         Returns:
-            A JobShopInstance object.
+            A :class:`JobShopInstance` object.
         """
         jobs: list[list[Operation]] = [[] for _ in range(len(duration_matrix))]
 
@@ -222,7 +283,7 @@ class JobShopInstance:
 
     @functools.cached_property
     def is_flexible(self) -> bool:
-        """Returns True if any operation has more than one machine."""
+        """Returns ``True`` if any operation has more than one machine."""
         return any(
             any(len(operation.machines) > 1 for operation in job)
             for job in self.jobs
@@ -232,12 +293,14 @@ class JobShopInstance:
     def durations_matrix(self) -> list[list[int]]:
         """Returns the duration matrix of the instance.
 
-        The duration 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:
+        The duration 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:
+
+        .. code-block:: python
+
+            duration = instance.durations_matrix[i][j]
 
-        ```python
-        duration = instance.durations_matrix[i][j]
-        ```
         """
         return [[operation.duration for operation in job] for job in self.jobs]
 
@@ -254,9 +317,9 @@ class JobShopInstance:
         To access the machines of the operation with position i in the job
         with id j, the following code must be used:
 
-        ```python
-        machines = instance.machines_matrix[j][i]
-        ```
+        .. code-block:: python
+
+            machines = instance.machines_matrix[j][i]
 
         """
         if self.is_flexible:
@@ -271,8 +334,9 @@ class JobShopInstance:
     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.
+        The returned array has shape (``num_jobs``,
+        ``max_num_operations_per_job``).
+        Non-existing operations are filled with ``np.nan``.
 
         Example:
             >>> jobs = [[Operation(0, 2), Operation(1, 3)], [Operation(0, 4)]]
@@ -288,9 +352,9 @@ class JobShopInstance:
     def machines_matrix_array(self) -> NDArray[np.float32]:
         """Returns the machines matrix of the instance as a numpy array.
 
-        The returned array has shape (num_jobs, max_num_operations_per_job,
-        max_num_machines_per_operation). Non-existing machines are filled with
-        np.nan.
+        The returned array has shape (``num_jobs``,
+        ``max_num_operations_per_job``, ``max_num_machines_per_operation``).
+        Non-existing machines are filled with ``np.nan``.
 
         Example:
             >>> jobs = [
@@ -413,7 +477,7 @@ class JobShopInstance:
     def _fill_matrix_with_nans_2d(
         matrix: list[list[int]],
     ) -> NDArray[np.float32]:
-        """Fills a matrix with np.nan values.
+        """Fills a matrix with ``np.nan`` values.
 
         Args:
             matrix:
@@ -421,7 +485,7 @@ class JobShopInstance:
 
         Returns:
             A numpy array with the same shape as the input matrix, filled with
-            np.nan values.
+            ``np.nan`` values.
         """
         max_length = max(len(row) for row in matrix)
         squared_matrix = np.full(
@@ -435,7 +499,7 @@ class JobShopInstance:
     def _fill_matrix_with_nans_3d(
         matrix: list[list[list[int]]],
     ) -> NDArray[np.float32]:
-        """Fills a 3D matrix with np.nan values.
+        """Fills a 3D matrix with ``np.nan`` values.
 
         Args:
             matrix:
@@ -443,7 +507,7 @@ class JobShopInstance:
 
         Returns:
             A numpy array with the same shape as the input matrix, filled with
-            np.nan values.
+            ``np.nan`` values.
         """
         max_length = max(len(row) for row in matrix)
         max_inner_length = len(matrix[0][0])

job_shop_lib/_operation.py

@@ -42,17 +42,28 @@ class Operation:
             "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.",
+        "job_id": (
+            "The id of the job the operation belongs to. Defaults to -1. "
+            "It is usually set by the :class:`JobShopInstance` class after "
+            "initialization."
+        ),
+        "position_in_job": (
+            "The index of the operation in the job. Defaults to -1. "
+            "It is usually set by the :class:`JobShopInstance` class after "
+            "initialization."
+        ),
         "operation_id": (
             "The id of the operation. This is unique within a "
-            ":class:`JobShopInstance`."
+            ":class:`JobShopInstance`. Defaults to -1. It is usually set by "
+            "the :class:`JobShopInstance` class after initialization."
         ),
     }
 
     def __init__(self, machines: int | list[int], duration: int):
-        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
@@ -64,8 +75,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/_schedule.py

@@ -25,6 +25,16 @@ class Schedule:
         is_complete
         add
         reset
+
+    Args:
+        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. If
+            not provided, the schedule is initialized as an empty schedule.
+        **metadata:
+            Additional information about the schedule.
     """
 
     __slots__ = {
@@ -46,28 +56,16 @@ class Schedule:
         self,
         instance: JobShopInstance,
         schedule: list[list[ScheduledOperation]] | None = None,
-        **metadata,
+        **metadata: Any,
     ):
-        """Initializes the object with the given instance and schedule.
-
-        Args:
-            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. If
-                not provided, the schedule is initialized as an empty schedule.
-            **metadata:
-                Additional information about the schedule.
-        """
         if schedule is None:
             schedule = [[] for _ in range(instance.num_machines)]
 
         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/_scheduled_operation.py

@@ -5,7 +5,21 @@ from job_shop_lib.exceptions import ValidationError
 
 
 class ScheduledOperation:
-    """Data structure to store a scheduled operation."""
+    """Data structure to store a scheduled operation.
+
+    Args:
+        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.
+
+    Raises:
+        ValidationError:
+            If the given machine_id is not in the list of valid machines
+            for the operation.
+    """
 
     __slots__ = {
         "operation": "The :class:`Operation` object that is scheduled.",
@@ -16,23 +30,8 @@ class ScheduledOperation:
     }
 
     def __init__(self, operation: Operation, start_time: int, machine_id: int):
-        """Initializes a new instance of the :class:`ScheduledOperation` class.
-
-        Args:
-            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.
-
-        Raises:
-            ValidationError:
-                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/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/dispatching/_dispatcher.py

@@ -29,6 +29,18 @@ class DispatcherObserver(abc.ABC):
         dispatcher:
             The :class:`Dispatcher` instance to observe.
 
+    Args:
+        dispatcher:
+            The :class:`Dispatcher` instance to observe.
+        subscribe:
+            If ``True``, automatically subscribes the observer to the
+            dispatcher when it is initialized. Defaults to ``True``.
+
+    Raises:
+        ValidationError: If ``is_singleton`` is ``True`` and an observer of the
+            same type already exists in the dispatcher's list of
+            subscribers.
+
     Example:
 
     .. code-block:: python
@@ -61,21 +73,6 @@ class DispatcherObserver(abc.ABC):
         *,
         subscribe: bool = True,
     ):
-        """Initializes the observer with the :class:`Dispatcher` and subscribes
-        to it.
-
-        Args:
-            dispatcher:
-                The `Dispatcher` instance to observe.
-            subscribe:
-                If True, automatically subscribes the observer to the
-                dispatcher.
-
-        Raises:
-            ValidationError: If ``is_singleton`` is True and an observer of the
-                same type already exists in the dispatcher's list of
-                subscribers.
-        """
         if self._is_singleton and any(
             isinstance(observer, self.__class__)
             for observer in dispatcher.subscribers
@@ -156,26 +153,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 +185,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 +360,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 +376,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 +432,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 +441,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/dispatching/_dispatcher_observer_config.py

@@ -26,14 +26,21 @@ class DispatcherObserverConfig(Generic[T]):
     keyword arguments to pass to the dispatcher observer constructor while
     not containing the ``dispatcher`` argument.
 
-    Attributes:
+    Args:
         class_type:
             Type of the class to be initialized. It can be the class type, an
             enum value, or a string. This is useful for the creation of
-            DispatcherObserver instances from the factory functions.
+            :class:`~job_shop_lib.dispatching.DispatcherObserver` instances
+            from the factory functions.
         kwargs:
             Keyword arguments needed to initialize the class. It must not
             contain the ``dispatcher`` argument.
+
+    .. seealso::
+
+        - :class:`~job_shop_lib.dispatching.DispatcherObserver`
+        - :func:`job_shop_lib.dispatching.feature_observers.\\
+          feature_observer_factory`
     """
 
     # We use the type hint T, instead of ObserverType, to allow for string or
@@ -44,7 +51,13 @@ class DispatcherObserverConfig(Generic[T]):
     # This allows for the creation of a FeatureObserver instance
     # from the factory function.
     class_type: T
+    """Type of the class to be initialized. It can be the class type, an
+    enum value, or a string. This is useful for the creation of
+    :class:`DispatcherObserver` instances from the factory functions."""
+
     kwargs: dict[str, Any] = field(default_factory=dict)
+    """Keyword arguments needed to initialize the class. It must not
+    contain the ``dispatcher`` argument."""
 
     def __post_init__(self):
         if "dispatcher" in self.kwargs:

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(
@@ -47,13 +51,13 @@ def create_composite_operation_filter(
             'non_immediate_machines' or any Callable that takes a
             :class:`~job_shop_lib.dispatching.Dispatcher` instance and a list
             of :class:`~job_shop_lib.Operation` instances as input
-            and returns a list of :class:`~job_shop_lib.Operation`instances.
+            and returns a list of :class:`~job_shop_lib.Operation` instances.
 
     Returns:
         A function that takes a :class:`~job_shop_lib.dispatching.Dispatcher`
         instance and a list of :class:`~job_shop_lib.Operation`
         instances as input and returns a list of
-        :class:`~job_shop_lib.Operation`instances based on
+        :class:`~job_shop_lib.Operation` instances based on
         the specified list of filter strategies.
 
     Raises:
@@ -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: