job-shop-lib 1.1.2__tar.gz → 1.2.0__tar.gz

{job_shop_lib-1.1.2 → job_shop_lib-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: job-shop-lib
-Version: 1.1.2
+Version: 1.2.0
 Summary: An easy-to-use and modular Python library for the Job Shop Scheduling Problem (JSSP)
 License: MIT
 Author: Pabloo22
@@ -86,6 +86,24 @@ pip install job-shop-lib
 
 <!-- end key features -->
 
+## Publication :scroll:
+
+For an in-depth explanation of the library (v1.0.0), including its design, features, reinforcement learning environments, and some experiments, please refer to my [Bachelor's thesis](https://www.arxiv.org/abs/2506.13781).
+
+You can also cite the library using the following BibTeX entry:
+
+```bibtex
+@misc{arino2025jobshoplib,
+      title={Solving the Job Shop Scheduling Problem with Graph Neural Networks: A Customizable Reinforcement Learning Environment}, 
+      author={Pablo Ariño Fernández},
+      year={2025},
+      eprint={2506.13781},
+      archivePrefix={arXiv},
+      primaryClass={cs.LG},
+      url={https://arxiv.org/abs/2506.13781}, 
+}
+```
+
 ## Some Examples :rocket:
 
 ### Create a Job Shop Instance
@@ -330,31 +348,82 @@ plt.show()
 
 The library generalizes this graph by allowing the addition of job nodes and a global one (see `build_resource_task_graph_with_jobs` and `build_resource_task_graph`).
 
-For more details, check the [examples](examples) folder.
+### Gymnasium Environments
 
-## Installation for development
+<div align="center">
+<img src="docs/source/images/rl_diagram.png">
+</div>
+<br>
 
-<!-- start installation development -->
 
-1. Clone the repository.
+The `SingleJobShopGraphEnv` allows to learn from a single job shop instance, while the `MultiJobShopGraphEnv` generates a new instance at each reset. For an in-depth explanation of the environments see chapter 7 of my [Bachelor's thesis](https://www.arxiv.org/abs/2506.13781).
 
-```bash
-git clone https://github.com/Pabloo22/job_shop_lib.git
-cd job_shop_lib
-```
+```python
+from IPython.display import clear_output
+
+from job_shop_lib.reinforcement_learning import (
+    # MakespanReward,
+    SingleJobShopGraphEnv,
+    ObservationSpaceKey,
+    IdleTimeReward,
+    ObservationDict,
+)
+from job_shop_lib.dispatching.feature_observers import (
+    FeatureObserverType,
+    FeatureType,
+)
+from job_shop_lib.dispatching import DispatcherObserverConfig
+
+
+instance = load_benchmark_instance("ft06")
+job_shop_graph = build_disjunctive_graph(instance)
+feature_observer_configs = [
+    DispatcherObserverConfig(
+        FeatureObserverType.IS_READY,
+        kwargs={"feature_types": [FeatureType.JOBS]},
+    )
+]
+
+env = SingleJobShopGraphEnv(
+    job_shop_graph=job_shop_graph,
+    feature_observer_configs=feature_observer_configs,
+    reward_function_config=DispatcherObserverConfig(IdleTimeReward),
+    render_mode="human",  # Try "save_video"
+    render_config={
+        "video_config": {"fps": 4}
+    }
+)
 
-2. Install [poetry](https://python-poetry.org/docs/) if you don't have it already:
 
-```bash
-pip install poetry
-```
+def random_action(observation: ObservationDict) -> tuple[int, int]:
+    ready_jobs = []
+    for job_id, is_ready in enumerate(
+        observation[ObservationSpaceKey.JOBS.value].ravel()
+    ):
+        if is_ready == 1.0:
+            ready_jobs.append(job_id)
 
-3. Install dependencies:
-```bash
-make poetry_install_all 
+    job_id = random.choice(ready_jobs)
+    machine_id = -1  # We can use -1 if each operation can only be scheduled
+    # on one machine.
+    return (job_id, machine_id)
+
+
+done = False
+obs, _ = env.reset()
+while not done:
+    action = random_action(obs)
+    obs, reward, done, *_ = env.step(action)
+    if env.render_mode == "human":
+        env.render()
+        clear_output(wait=True)
+
+if env.render_mode == "save_video" or env.render_mode == "save_gif":
+    env.render()
 ```
 
-<!-- end installation development -->
+## Contributing :handshake:
+Any contribution is welcome, whether it's a small bug or documentation fix or a new feature! See the [CONTRIBUTING.md](CONTRIBUTING.md) file for details on how to contribute to this project.
 
 ## License :scroll:
 
@@ -391,5 +460,5 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
  - E. Taillard, "Benchmarks for basic scheduling problems," European
      Journal of Operational Research, vol. 64, no. 2, pp. 278–285, 1993.
 
-- Park, Junyoung, Sanjar Bakhtiyar, and Jinkyoo Park. "ScheduleNet: Learn to solve multi-agent scheduling problems with reinforcement learning." arXiv preprint arXiv:2106.03051, 2021. 
+  - Park, Junyoung, Sanjar Bakhtiyar, and Jinkyoo Park. "ScheduleNet: Learn to solve multi-agent scheduling problems with reinforcement learning." arXiv preprint arXiv:2106.03051, 2021. 
 

{job_shop_lib-1.1.2 → job_shop_lib-1.2.0}/README.md

@@ -61,6 +61,24 @@ pip install job-shop-lib
 
 <!-- end key features -->
 
+## Publication :scroll:
+
+For an in-depth explanation of the library (v1.0.0), including its design, features, reinforcement learning environments, and some experiments, please refer to my [Bachelor's thesis](https://www.arxiv.org/abs/2506.13781).
+
+You can also cite the library using the following BibTeX entry:
+
+```bibtex
+@misc{arino2025jobshoplib,
+      title={Solving the Job Shop Scheduling Problem with Graph Neural Networks: A Customizable Reinforcement Learning Environment}, 
+      author={Pablo Ariño Fernández},
+      year={2025},
+      eprint={2506.13781},
+      archivePrefix={arXiv},
+      primaryClass={cs.LG},
+      url={https://arxiv.org/abs/2506.13781}, 
+}
+```
+
 ## Some Examples :rocket:
 
 ### Create a Job Shop Instance
@@ -305,31 +323,82 @@ plt.show()
 
 The library generalizes this graph by allowing the addition of job nodes and a global one (see `build_resource_task_graph_with_jobs` and `build_resource_task_graph`).
 
-For more details, check the [examples](examples) folder.
+### Gymnasium Environments
 
-## Installation for development
+<div align="center">
+<img src="docs/source/images/rl_diagram.png">
+</div>
+<br>
 
-<!-- start installation development -->
 
-1. Clone the repository.
+The `SingleJobShopGraphEnv` allows to learn from a single job shop instance, while the `MultiJobShopGraphEnv` generates a new instance at each reset. For an in-depth explanation of the environments see chapter 7 of my [Bachelor's thesis](https://www.arxiv.org/abs/2506.13781).
 
-```bash
-git clone https://github.com/Pabloo22/job_shop_lib.git
-cd job_shop_lib
-```
+```python
+from IPython.display import clear_output
+
+from job_shop_lib.reinforcement_learning import (
+    # MakespanReward,
+    SingleJobShopGraphEnv,
+    ObservationSpaceKey,
+    IdleTimeReward,
+    ObservationDict,
+)
+from job_shop_lib.dispatching.feature_observers import (
+    FeatureObserverType,
+    FeatureType,
+)
+from job_shop_lib.dispatching import DispatcherObserverConfig
+
+
+instance = load_benchmark_instance("ft06")
+job_shop_graph = build_disjunctive_graph(instance)
+feature_observer_configs = [
+    DispatcherObserverConfig(
+        FeatureObserverType.IS_READY,
+        kwargs={"feature_types": [FeatureType.JOBS]},
+    )
+]
+
+env = SingleJobShopGraphEnv(
+    job_shop_graph=job_shop_graph,
+    feature_observer_configs=feature_observer_configs,
+    reward_function_config=DispatcherObserverConfig(IdleTimeReward),
+    render_mode="human",  # Try "save_video"
+    render_config={
+        "video_config": {"fps": 4}
+    }
+)
 
-2. Install [poetry](https://python-poetry.org/docs/) if you don't have it already:
 
-```bash
-pip install poetry
-```
+def random_action(observation: ObservationDict) -> tuple[int, int]:
+    ready_jobs = []
+    for job_id, is_ready in enumerate(
+        observation[ObservationSpaceKey.JOBS.value].ravel()
+    ):
+        if is_ready == 1.0:
+            ready_jobs.append(job_id)
 
-3. Install dependencies:
-```bash
-make poetry_install_all 
+    job_id = random.choice(ready_jobs)
+    machine_id = -1  # We can use -1 if each operation can only be scheduled
+    # on one machine.
+    return (job_id, machine_id)
+
+
+done = False
+obs, _ = env.reset()
+while not done:
+    action = random_action(obs)
+    obs, reward, done, *_ = env.step(action)
+    if env.render_mode == "human":
+        env.render()
+        clear_output(wait=True)
+
+if env.render_mode == "save_video" or env.render_mode == "save_gif":
+    env.render()
 ```
 
-<!-- end installation development -->
+## Contributing :handshake:
+Any contribution is welcome, whether it's a small bug or documentation fix or a new feature! See the [CONTRIBUTING.md](CONTRIBUTING.md) file for details on how to contribute to this project.
 
 ## License :scroll:
 
@@ -366,4 +435,4 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
  - E. Taillard, "Benchmarks for basic scheduling problems," European
      Journal of Operational Research, vol. 64, no. 2, pp. 278–285, 1993.
 
-- Park, Junyoung, Sanjar Bakhtiyar, and Jinkyoo Park. "ScheduleNet: Learn to solve multi-agent scheduling problems with reinforcement learning." arXiv preprint arXiv:2106.03051, 2021. 
+  - Park, Junyoung, Sanjar Bakhtiyar, and Jinkyoo Park. "ScheduleNet: Learn to solve multi-agent scheduling problems with reinforcement learning." arXiv preprint arXiv:2106.03051, 2021. 

{job_shop_lib-1.1.2 → job_shop_lib-1.2.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.1.2"
+__version__ = "1.2.0"
 
 __all__ = [
     "Operation",

{job_shop_lib-1.1.2 → job_shop_lib-1.2.0}/job_shop_lib/dispatching/__init__.py

@@ -24,6 +24,7 @@ Problem step-by-step.
     get_matrix_setup_time_calculator
     get_breakdown_calculator
     get_job_dependent_setup_calculator
+    get_arrival_calculator
 
 Dispatching refers to the decision-making process of selecting which job
 should be processed next on a particular machine when that machine becomes
@@ -53,6 +54,7 @@ from ._start_time_calculators import (
     get_breakdown_calculator,
     get_job_dependent_setup_calculator,
     get_matrix_setup_time_calculator,
+    get_arrival_calculator,
 )
 from ._dispatcher_observer_config import DispatcherObserverConfig
 from ._factories import (
@@ -84,4 +86,5 @@ __all__ = [
     "get_matrix_setup_time_calculator",
     "get_breakdown_calculator",
     "get_job_dependent_setup_calculator",
+    "get_arrival_calculator",
 ]

{job_shop_lib-1.1.2 → job_shop_lib-1.2.0}/job_shop_lib/dispatching/_start_time_calculators.py

@@ -193,3 +193,52 @@ def get_job_dependent_setup_calculator(
         return default_start + setup_time
 
     return calculator
+
+
+def get_arrival_calculator(
+    arrival_times: Sequence[Sequence[int]] | NDArray[np.integer] | None = None,
+) -> StartTimeCalculator:
+    """Returns a start time calculator that respects operation arrival times.
+
+    This calculator uses a predefined matrix of arrival times to
+    ensure that no operation begins before its specified arrival
+    time. If the ``arrival_times`` matrix isn't provided directly,
+    the calculator attempts to retrieve it from the dispatcher's
+    instance metadata using the key ``"arrival_times_matrix"``.
+
+    Args:
+        arrival_times:
+            A 2D matrix where ``arrival_times[i][j]`` is the
+            arrival time for the operation at index ``j`` of
+            job ``i``. If ``None``, the calculator will
+            attempt to retrieve it from the dispatcher metadata.
+
+    Returns:
+        A start time calculator function that uses the arrival times.
+
+    Example:
+        >>> arrival_calc = get_arrival_calculator([[0, 2], [1, 0]])
+        >>> dispatcher = Dispatcher(
+        ...     instance, start_time_calculator=arrival_calc
+        ... )
+    """
+
+    def calculator(
+        dispatcher: Dispatcher, operation: Operation, machine_id: int
+    ) -> int:
+        default_start_time = no_setup_time_calculator(
+            dispatcher, operation, machine_id
+        )
+        arrival_matrix = arrival_times
+        if arrival_matrix is None:
+            arrival_matrix = dispatcher.instance.metadata.get(
+                "arrival_times_matrix"
+            )
+        if arrival_matrix is None:
+            return default_start_time
+        operation_arrival_time = arrival_matrix[operation.job_id][
+            operation.position_in_job
+        ]
+        return max(default_start_time, operation_arrival_time)
+
+    return calculator

{job_shop_lib-1.1.2 → job_shop_lib-1.2.0}/job_shop_lib/dispatching/feature_observers/_feature_observer.py

@@ -92,6 +92,9 @@ class FeatureObserver(DispatcherObserver):
                 feature_type: self._feature_sizes
                 for feature_type in feature_types
             }
+        else:
+            feature_size = self._feature_sizes
+
         super().__init__(dispatcher, subscribe=subscribe)
 
         number_of_entities = {

{job_shop_lib-1.1.2 → job_shop_lib-1.2.0}/job_shop_lib/dispatching/rules/_dispatching_rules_functions.py

@@ -35,7 +35,23 @@ def first_come_first_served_rule(dispatcher: Dispatcher) -> Operation:
 
 
 def most_work_remaining_rule(dispatcher: Dispatcher) -> Operation:
-    """Dispatches the operation which job has the most remaining work."""
+    """Dispatches the operation which job has the most remaining work.
+
+    The remaining work of a job is defined as the sum of the durations of
+    all unscheduled operations in that job. The operation with the highest
+    remaining work is selected for dispatching. Note that uncompleted
+    but scheduled operations are not considered in this rule, only
+    unscheduled operations are taken into account.
+
+    Args:
+        dispatcher:
+            The :class:`~job_shop_lib.dispatching.Dispatcher` instance
+            containing the job shop instance and the current state of the
+            schedule.
+
+    Returns:
+        The operation that belongs to the job with the most remaining work.
+    """
     job_remaining_work = [0] * dispatcher.instance.num_jobs
     for operation in dispatcher.unscheduled_operations():
         job_remaining_work[operation.job_id] += operation.duration
@@ -47,7 +63,23 @@ def most_work_remaining_rule(dispatcher: Dispatcher) -> Operation:
 
 
 def most_operations_remaining_rule(dispatcher: Dispatcher) -> Operation:
-    """Dispatches the operation which job has the most remaining operations."""
+    """Dispatches the operation which job has the most remaining operations.
+
+    The remaining operations of a job are defined as the number of
+    uncompleted operations in that job. The operation with the highest
+    number of remaining operations is selected for dispatching. Note that
+    uncompleted but scheduled operations are considered in this rule.
+
+    Args:
+        dispatcher:
+            The :class:`~job_shop_lib.dispatching.Dispatcher` instance
+            containing the job shop instance and the current state of the
+            schedule.
+
+    Returns:
+        The operation that belongs to the job with the most remaining
+        operations.
+    """
     job_remaining_operations = [0] * dispatcher.instance.num_jobs
     for operation in dispatcher.uncompleted_operations():
         job_remaining_operations[operation.job_id] += 1
@@ -69,7 +101,9 @@ def score_based_rule(
     """Creates a dispatching rule based on a scoring function.
 
     Args:
-        score_function: A function that takes a Dispatcher instance as input
+        score_function:
+            A function that takes a
+            :class:`~job_shop_lib.dispatching.Dispatcher` instance as input
             and returns a list of scores for each job.
 
     Returns:
@@ -97,7 +131,9 @@ def score_based_rule_with_tie_breaker(
     still a tie, the third scoring function is used, and so on.
 
     Args:
-        score_functions: A list of scoring functions that take a Dispatcher
+        score_functions
+            A list of scoring functions that take a
+            :class:`~job_shop_lib.dispatching.Dispatcher`
             instance as input and return a list of scores for each job.
     """
 
@@ -123,7 +159,21 @@ def score_based_rule_with_tie_breaker(
 
 
 def shortest_processing_time_score(dispatcher: Dispatcher) -> list[int]:
-    """Scores each job based on the duration of the next operation."""
+    """Scores each job based on the duration of the next operation.
+
+    The score is the negative duration of the next operation in each job.
+    This means that jobs with shorter next operations will have higher scores.
+
+    Args:
+        dispatcher:
+            The :class:`~job_shop_lib.dispatching.Dispatcher` instance
+            containing the job shop instance and the current state of the
+            schedule.
+
+    Returns:
+        A list of scores for each job, where the score is the negative
+        duration of the next operation in that job.
+    """
     num_jobs = dispatcher.instance.num_jobs
     scores = [0] * num_jobs
     for operation in dispatcher.available_operations():
@@ -132,11 +182,26 @@ def shortest_processing_time_score(dispatcher: Dispatcher) -> list[int]:
 
 
 def first_come_first_served_score(dispatcher: Dispatcher) -> list[int]:
-    """Scores each job based on the position of the next operation."""
+    """Scores each job based on the position of the next operation.
+
+    The score is the negative position of the next operation in each job.
+    This means that jobs with operations that are earlier in the job will have
+    higher scores.
+
+    Args:
+        dispatcher:
+            The :class:`~job_shop_lib.dispatching.Dispatcher` instance
+            containing the job shop instance and the current state of the
+            schedule.
+
+    Returns:
+        A list of scores for each job, where the score is the negative
+        position of the next operation in that job.
+    """
     num_jobs = dispatcher.instance.num_jobs
     scores = [0] * num_jobs
     for operation in dispatcher.available_operations():
-        scores[operation.job_id] = operation.operation_id
+        scores[operation.job_id] = -operation.operation_id
     return scores
 
 
@@ -145,8 +210,8 @@ class MostWorkRemainingScorer:  # pylint: disable=too-few-public-methods
 
     This class is conceptually a function: it can be called with a
     :class:`~job_shop_lib.dispatching.Dispatcher` instance as input, and it
-    returns a list of scores for each job. The reason for using a class instead
-    of a function is to cache the observers that are created for each
+    returns a list of scores for each job. The reason for using a class
+    instead of a function is to cache the observers that are created for each
     dispatcher instance. This way, the observers do not have to be retrieved
     every time the function is called.
 
@@ -195,10 +260,26 @@ class MostWorkRemainingScorer:  # pylint: disable=too-few-public-methods
 observer_based_most_work_remaining_rule = score_based_rule(
     MostWorkRemainingScorer()
 )
+"""Dispatching rule that uses the :class:`MostWorkRemainingScorer` to select
+the next operation."""
 
 
 def most_operations_remaining_score(dispatcher: Dispatcher) -> list[int]:
-    """Scores each job based on the remaining operations in the job."""
+    """Scores each job based on the remaining operations in the job.
+
+    The score is the number of uncompleted operations in each job. This means
+    that jobs with more uncompleted operations will have higher scores.
+
+    Args:
+        dispatcher:
+            The :class:`~job_shop_lib.dispatching.Dispatcher` instance
+            containing the job shop instance and the current state of the
+            schedule.
+
+    Returns:
+        A list of scores for each job, where the score is the number of
+        uncompleted operations in that job.
+    """
     num_jobs = dispatcher.instance.num_jobs
     scores = [0] * num_jobs
     for operation in dispatcher.uncompleted_operations():
@@ -207,7 +288,21 @@ def most_operations_remaining_score(dispatcher: Dispatcher) -> list[int]:
 
 
 def random_score(dispatcher: Dispatcher) -> list[int]:
-    """Scores each job randomly."""
+    """Scores each job randomly.
+
+    This function generates a random score for each job in the job shop
+    instance. The scores are integers between 0 and 100, inclusive.
+
+    Args:
+        dispatcher:
+            The :class:`~job_shop_lib.dispatching.Dispatcher` instance
+            containing the job shop instance and the current state of the
+            schedule.
+
+    Returns:
+        A list of random scores for each job, where each score is an integer
+        between 0 and 100.
+    """
     return [
         random.randint(0, 100) for _ in range(dispatcher.instance.num_jobs)
     ]

{job_shop_lib-1.1.2 → job_shop_lib-1.2.0}/job_shop_lib/generation/_instance_generator.py

@@ -1,6 +1,6 @@
 """Home of the `InstanceGenerator` class."""
 
-import abc
+from abc import ABC, abstractmethod
 
 import random
 from typing import Iterator
@@ -9,7 +9,7 @@ from job_shop_lib import JobShopInstance
 from job_shop_lib.exceptions import UninitializedAttributeError
 
 
-class InstanceGenerator(abc.ABC):
+class InstanceGenerator(ABC):
     """Common interface for all generators.
 
     The class supports both single instance generation and iteration over
@@ -75,7 +75,7 @@ class InstanceGenerator(abc.ABC):
         self._current_iteration = 0
         self._iteration_limit = iteration_limit
 
-    @abc.abstractmethod
+    @abstractmethod
     def generate(
         self,
         num_jobs: int | None = None,

{job_shop_lib-1.1.2 → job_shop_lib-1.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "job-shop-lib"
-version = "1.1.2"
+version = "1.2.0"
 description = "An easy-to-use and modular Python library for the Job Shop Scheduling Problem (JSSP)"
 authors = ["Pabloo22 <pablete.arino@gmail.com>"]
 license = "MIT"
@@ -64,7 +64,7 @@ ipython = "^8.31.0"
 pygraphviz = ["pygraphviz"]
 
 [build-system]
-requires = ["poetry-core"]
+requires = ["poetry-core==1.8.2"]  # Enforces specific Poetry version
 build-backend = "poetry.core.masonry.api"
 
 [tool.black]