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

job_shop_lib/_job_shop_instance.py

@@ -15,16 +15,47 @@ 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 (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.
+            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 (dict[str, Any]):
@@ -34,11 +65,16 @@ class JobShopInstance:
         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
+            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.
     """
@@ -47,15 +83,37 @@ class JobShopInstance:
         self,
         jobs: list[list[Operation]],
         name: str = "JobShopInstance",
+        set_operation_attributes: bool = True,
         **metadata: Any,
     ):
         self.jobs: list[list[Operation]] = jobs
-        self.set_operation_attributes()
+        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 and position of each operation."""
+        """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
+
+        """
+
         operation_id = 0
         for job_id, job in enumerate(self.jobs):
             for position, operation in enumerate(job):
@@ -90,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()
@@ -128,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,
@@ -151,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:
@@ -168,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))]
 
@@ -220,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
@@ -230,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]
 
@@ -252,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:
@@ -269,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)]]
@@ -286,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 = [
@@ -411,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:
@@ -419,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(
@@ -433,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:
@@ -441,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,11 +42,20 @@ 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."
         ),
     }
 

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__ = {
@@ -48,18 +58,6 @@ class Schedule:
         schedule: list[list[ScheduledOperation]] | None = None,
         **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)]
 

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,21 +30,6 @@ 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 = operation
         self.start_time: int = start_time
         self._machine_id = machine_id

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

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

@@ -51,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:

job_shop_lib/dispatching/feature_observers/_composite_feature_observer.py

@@ -193,7 +193,6 @@ if __name__ == "__main__":
             dispatcher=dispatcher_,
         )
         for observer_type in feature_observer_types_
-        if not observer_type == FeatureObserverType.COMPOSITE
         # and not FeatureObserverType.EARLIEST_START_TIME
     ]
     composite_observer_ = CompositeFeatureObserver(

job_shop_lib/dispatching/feature_observers/_factory.py

@@ -1,4 +1,4 @@
-"""Contains factory functions for creating node feature encoders."""
+"""Contains factory functions for creating :class:`FeatureObserver`s."""
 
 from enum import Enum
 
@@ -18,8 +18,12 @@ from job_shop_lib.dispatching.feature_observers import (
 class FeatureObserverType(str, Enum):
     """Enumeration of the different feature observers.
 
-    Each feature observer is associated with a string value that can be used
-    to create the feature observer using the factory function.
+    Each :class:`FeatureObserver` is associated with a string value that can be
+    used to create the :class:`FeatureObserver` using the factory function.
+
+    It does not include the :class:`CompositeFeatureObserver` class since this
+    observer is often managed separately from the others. For example, a
+    common use case is to create a list of feature observers and pass them to
     """
 
     IS_READY = "is_ready"
@@ -29,7 +33,6 @@ class FeatureObserverType(str, Enum):
     POSITION_IN_JOB = "position_in_job"
     REMAINING_OPERATIONS = "remaining_operations"
     IS_COMPLETED = "is_completed"
-    COMPOSITE = "composite"
 
 
 # FeatureObserverConfig = DispatcherObserverConfig[
@@ -43,7 +46,7 @@ FeatureObserverConfig = (
 
 
 def feature_observer_factory(
-    feature_creator_type: (
+    feature_observer_type: (
         str
         | FeatureObserverType
         | type[FeatureObserver]
@@ -51,29 +54,29 @@ def feature_observer_factory(
     ),
     **kwargs,
 ) -> FeatureObserver:
-    """Creates and returns a node feature creator based on the specified
-    node feature creator type.
+    """Creates and returns a :class:`FeatureObserver` based on the specified
+    :class:`FeatureObserver` type.
 
     Args:
         feature_creator_type:
-            The type of node feature creator to create.
+            The type of :class:`FeatureObserver` to create.
         **kwargs:
-            Additional keyword arguments to pass to the node
-            feature creator constructor.
+            Additional keyword arguments to pass to the
+            :class:`FeatureObserver` constructor.
 
     Returns:
-        A node feature creator instance.
+        A :class:`FeatureObserver` instance.
     """
-    if isinstance(feature_creator_type, DispatcherObserverConfig):
+    if isinstance(feature_observer_type, DispatcherObserverConfig):
         return feature_observer_factory(
-            feature_creator_type.class_type,
-            **feature_creator_type.kwargs,
+            feature_observer_type.class_type,
+            **feature_observer_type.kwargs,
             **kwargs,
         )
     # if the instance is of type type[FeatureObserver] we can just
     # call the object constructor with the keyword arguments
-    if isinstance(feature_creator_type, type):
-        return feature_creator_type(**kwargs)
+    if isinstance(feature_observer_type, type):
+        return feature_observer_type(**kwargs)
 
     mapping: dict[FeatureObserverType, type[FeatureObserver]] = {
         FeatureObserverType.IS_READY: IsReadyObserver,
@@ -84,5 +87,5 @@ def feature_observer_factory(
         FeatureObserverType.REMAINING_OPERATIONS: RemainingOperationsObserver,
         FeatureObserverType.IS_COMPLETED: IsCompletedObserver,
     }
-    feature_creator = mapping[feature_creator_type]  # type: ignore[index]
-    return feature_creator(**kwargs)
+    feature_observer = mapping[feature_observer_type]  # type: ignore[index]
+    return feature_observer(**kwargs)

job_shop_lib/dispatching/feature_observers/_is_completed_observer.py

@@ -51,6 +51,7 @@ class IsCompletedObserver(FeatureObserver):
     def __init__(
         self,
         dispatcher: Dispatcher,
+        *,
         feature_types: list[FeatureType] | FeatureType | None = None,
         subscribe: bool = True,
     ):

job_shop_lib/dispatching/rules/_dispatching_rule_solver.py

@@ -55,7 +55,7 @@ class DispatchingRuleSolver(BaseSolver):
             - a list with names or actual ready operations filters to be used.
               If a list is provided, a composite filter will be created
               using the specified filters.
-    
+
     .. seealso::
         - :func:`job_shop_lib.dispatching.rules.dispatching_rule_factory`
         - :func:`job_shop_lib.dispatching.rules.machine_chooser_factory`