From 725b1eb63836cf2d1800ebae15161db74ea36224 Mon Sep 17 00:00:00 2001 From: Pabloo22 Date: Sun, 23 Nov 2025 17:08:28 +0000 Subject: [PATCH 1/2] [Docs] Improve homepage structure (#85, #86) and fix typo in installation guide --- docs/source/index.rst | 97 +++++++++++++++++++++++++++++++++++------- docs/source/install.md | 2 +- 2 files changed, 83 insertions(+), 16 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index 164f6a14..e3664a3f 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -3,9 +3,8 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Welcome to JobShopLib's documentation! +JobShopLib ====================================== - **Version:** |version| .. image:: https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png @@ -14,30 +13,98 @@ Welcome to JobShopLib's documentation! :alt: GitHub :align: right -JobShopLib is a Python package for creating, solving, and visualizing -Job Shop Scheduling Problems (JSSP). +.. image:: examples/output/ft06_optimized.gif + :alt: JobShopLib example gif + :align: center + +JobShopLib is a Python package for **creating**, **solving**, and **visualizing** +job shop scheduling problems. + +It provides solvers based on: + +- **Graph neural networks** (Gymnasium environment) +- **Dispatching rules** +- **Simulated annealing** +- **Constraint programming** (CP-SAT from Google OR-Tools) + +It also includes utilities for: + +- **Load benchmark instances** +- **Generating random problems** +- **Gantt charts** +- **Disjunctive graphs** (and any variant) +- Training a GNN-based dispatcher using **reinforcement learning** or **imitation learning** + +JobShopLib design is intended to be modular and easy-to-use: + +.. code-block:: python + + import matplotlib.pyplot as plt + plt.style.use("ggplot") + + from job_shop_lib import JobShopInstance, Operation + from job_shop_lib.benchmarking import load_benchmark_instance + from job_shop_lib.generation import GeneralInstanceGenerator + from job_shop_lib.constraint_programming import ORToolsSolver + from job_shop_lib.visualization import plot_gantt_chart, create_gif, plot_gantt_chart_wrapper + from job_shop_lib.dispatching import DispatchingRuleSolver -It follows a modular design, allowing users to easily extend the library -with new solvers, dispatching rules, visualization functions, etc. + # Create your own instance manually, + job_1 = [Operation(machines=0, duration=1), Operation(1, 1), Operation(2, 7)] + job_2 = [Operation(1, 5), Operation(2, 1), Operation(0, 1)] + job_3 = [Operation(2, 1), Operation(0, 3), Operation(1, 2)] + jobs = [job_1, job_2, job_3] + instance = JobShopInstance(jobs) + + # load a popular benchmark instance, + ft06 = load_benchmark_instance("ft06") + + # or generate a random one. + generator = GeneralInstanceGenerator( + duration_range=(5, 10), seed=42, num_jobs=5, num_machines=5 + ) + random_instance = generator.generate() + + # Solve it using constraint programming, + solver = ORToolsSolver(max_time_in_seconds=10) + ft06_schedule = solver(ft06) + + # Visualize the solution as a Gantt chart, + fig, ax = plot_gantt_chart(ft06_schedule) + plt.show() + + # or visualize how the solution is built step by step using a dispatching rule. + mwkr_solver = DispatchingRuleSolver("most_work_remaining") + plt.style.use("ggplot") + plot_function = plot_gantt_chart_wrapper( + title="Solution with Most Work Remaining Rule" + ) + create_gif( # Creates the gif above + gif_path="ft06_optimized.gif", + instance=ft06, + solver=mwkr_solver, + plot_function=plot_function, + fps=4, + ) See `this `__ Google Colab notebook for a quick start guide! +Installing +----------- + +.. code-block:: bash + + pip install job_shop_lib + Contents -------- .. toctree:: - :maxdepth: 3 + :maxdepth: 1 install tutorial examples - api - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` + api \ No newline at end of file diff --git a/docs/source/install.md b/docs/source/install.md index 9bf4beed..47f45952 100644 --- a/docs/source/install.md +++ b/docs/source/install.md @@ -10,6 +10,6 @@ For plotting a disjunctive graph, we recommend using [Graphviz](https://graphviz - **macOS**: `brew install graphviz` - **Windows**: `choco install graphviz` or download the installer from the [Graphviz website](https://graphviz.org/download/). -## Developement +## Development See intructions in the [CONTRIBUTING.md](https://github.com/Pabloo22/job_shop_lib/blob/main/CONTRIBUTING.md) file. \ No newline at end of file From be29d7d1ba1a0e37b3be42a888e134bf32eb3b0a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pablo=20Ari=C3=B1o?= <72697714+Pabloo22@users.noreply.github.com> Date: Sun, 23 Nov 2025 17:11:25 +0000 Subject: [PATCH 2/2] [Docs] Fix typo Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- docs/source/install.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/install.md b/docs/source/install.md index 47f45952..38f4660b 100644 --- a/docs/source/install.md +++ b/docs/source/install.md @@ -12,4 +12,4 @@ For plotting a disjunctive graph, we recommend using [Graphviz](https://graphviz ## Development -See intructions in the [CONTRIBUTING.md](https://github.com/Pabloo22/job_shop_lib/blob/main/CONTRIBUTING.md) file. \ No newline at end of file +See instructions in the [CONTRIBUTING.md](https://github.com/Pabloo22/job_shop_lib/blob/main/CONTRIBUTING.md) file. \ No newline at end of file