docs

.readthedocs.yaml

+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version, and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/source/conf.py
+
+# Optionally, but recommended,
+# declare the Python requirements required to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+    install:
+    - requirements: requirements_dev.txt

docs/source/examples/example-gallery.md

@@ -2,12 +2,13 @@
 
 This gallery contains a collection of code snippets together with their corresponding output, illustrating the usages of
 the JSP instances with various state-of-the-art algorithms.
-sfd
 
 ```{toctree}
 :caption: 'Examples:'
 :maxdepth: 2
 
-
+graph-jsp-env_example
+graph-matrix-jsp-env_example
 JSSEnv_example
+or-tools_example
 ```

docs/source/index.md

@@ -8,7 +8,7 @@
 :caption: 'Contents:'
 :maxdepth: 2
 
-
+usage
 instances-table
 source-code-docs/source-code
 examples/example-gallery

docs/source/usage.md

+# Usage
+
+To get started, you need to install the package. You can do this by running the following command:
+
+```bash
+pip install jsp-instance-utils
+```
+Then you can import instances from the package and use them in your code. For example, to load an instance from the package.
+Here is an example of how to load the `ft06` instance from the package:
+```
+from jsp_instance_utils.instances import ft06
+from jsp_instance_utils.instances import ft06_makespan
+from jsp_instance_utils.instances import ft06_makespan_is_optimal
+```
+or you can do it in a more compact way:
+```
+from jsp_instance_utils.instances import ft06, ft06_makespan, ft06_makespan_is_optimal
+```
+
+The individual instances follow the naming in the Table of isntances.
+The `_makespan`-suffix indicates yields the lowest makespan of the instance that is known (cf. the cited literature).
+For small instances this is the optimal makespan, for larger instances it is the best known makespan.
+The `_makespan_is_optimal`-suffix indicates whether the `_makespan`-value is optimal or not.
+So `ft06` refers to the instance (in the format of this software package), `ft06_makespan` to the best known makespan, and `ft06_makespan_is_optimal` to whether the best known makespan is optimal or not.
+The `ft06` instance is a small instance with 6 jobs and 6 machines and was introduced by Fisher and Thompson in 1963.
+
+Here is another example of how to load the `ta01` instance from the package:
+```
+from jsp_instance_utils.instances import ta01, ta01_makespan, ta01_makespan_is_optimal
+```
+The `ta01` instance is a instance with 10 jobs and 10 machines and was introduced by Taillard in 1993.
+
+## Format of the Instances
+
+```{note}
+The machines are indexed starting from 0.
+```
+
+The instances in this package are represented as numpy arrays with shape `(n_jobs, n_machines, 2)`.
+here is a small example:
+
+```python
+import numpy as np
+custom_jsp_instance = np.array([
+    [
+        [0, 1, 2, 3],  # job 0 (machine0, machine1, machine2, machine3)
+        [0, 2, 1, 3]  # job 1 (machine0, machine1, machine2, machine3)
+    ],
+    [
+        [11, 3, 3, 12],  # task durations of job 0
+        [5, 16, 7, 4]  # task durations of job 1
+    ]
+])
+```
+This format is useful, because the individual matrices can easily be extracted.
+Here is an example:
+
+```python
+machine_matrix, processing_time_matrix = custom_jsp_instance
+```
+That way `machine_matrix` would be:
+
+```python
+np.array([
+    [0, 1, 2, 3],
+    [0, 2, 1, 3]
+])
+```
+and `processing_time_matrix` would be:
+
+```python
+np.array([
+    [11, 3, 3, 12],
+    [5, 16, 7, 4]
+])
+```
+
+Here is a complete runnable example of how to load the `ft06` instance from the package and how to extract the machine matrix and the processing time matrix:
+
+```python
+from jsp_instance_utils.instances import ft06, ft06_makespan, ft06_makespan_is_optimal
+
+machine_matrix, processing_times = ft06
+
+print(f"""
+The machine matrix of instance 'ft06' is:
+{machine_matrix}
+
+The processing times of instance 'ft06' are:
+{processing_times}
+
+The lowest known makespan of instance 'ft06' is:
+{ft06_makespan}
+The lowest known makespan is a {'optimal' if ft06_makespan_is_optimal else 'not necessarily optimal'} solution.
+""")
+    
+```
+
+This code snippet returns the following output:
+
+![ft06 instance screenshot](../_static/ft06_screenshot.png)
+
+Analogously, you can load the `ta01` instance from the package and extract the machine matrix and the processing time matrix:
+
+```python
+from jsp_instance_utils.instances import ta01, ta01_makespan, ta01_makespan_is_optimal
+
+machine_matrix, processing_times = ta01
+
+print(f"""
+The machine matrix of instance 'ft06' is:
+{machine_matrix}
+
+The processing times of instance 'ft06' are:
+{processing_times}
+
+The lowest known makespan of instance 'ft06' is:
+{ta01_makespan}
+The lowest known makespan is a {'optimal' if ta01_makespan_is_optimal else 'not necessarily optimal'} solution.
+""")
+```
+
+This code snippet yields the following output:
+
+![ta01 instance screenshot](../_static/ta01-screenshot.png)
+
+## Reinforcement Learning Environments
+
+For the usage of the instances in reinforcement learning environments, we provide a wrapper class that can be used to create a reinforcement learning environment please check out the {ref}`asdasd` of this project. 

examples/example-ft06.py

+from jsp_instance_utils.instances import ft06, ft06_makespan, ft06_makespan_is_optimal
+
+machine_matrix, processing_times = ft06
+
+print(f"""
+The machine matrix of instance 'ft06' is:
+{machine_matrix}
+
+The processing times of instance 'ft06' are:
+{processing_times}
+
+The lowest known makespan of instance 'ft06' is:
+{ft06_makespan}
+The lowest known makespan is a {'optimal' if ft06_makespan_is_optimal else 'not necessarily optimal'} solution.
+""")

examples/example-ta01.py

+from jsp_instance_utils.instances import ta01, ta01_makespan, ta01_makespan_is_optimal
+
+machine_matrix, processing_times = ta01
+
+print(f"""
+The machine matrix of instance 'ft06' is:
+{machine_matrix}
+
+The processing times of instance 'ft06' are:
+{processing_times}
+
+The lowest known makespan of instance 'ft06' is:
+{ta01_makespan}
+The lowest known makespan is a {'optimal' if ta01_makespan_is_optimal else 'not necessarily optimal'} solution.
+""")

requirements_dev.txt

@@ -14,6 +14,8 @@ anyio==4.9.0
     #   jupyter-server
     #   starlette
     #   watchfiles
+appnope==0.1.4
+    # via ipykernel
 argon2-cffi==23.1.0
     # via jupyter-server
 argon2-cffi-bindings==21.2.0
@@ -68,11 +70,6 @@ codecov==2.1.13
     # via jssenv
 colorama==0.4.6
     # via
-    #   build
-    #   click
-    #   ipython
-    #   pytest
-    #   sphinx
     #   sphinx-autobuild
     #   tox
 comm==0.2.2
@@ -357,6 +354,8 @@ pandocfilters==1.5.1
     # via nbconvert
 parso==0.8.4
     # via jedi
+pexpect==4.9.0
+    # via ipython
 pillow==11.1.0
     # via
     #   imageio
@@ -393,6 +392,10 @@ psutil==7.0.0
     # via
     #   ipykernel
     #   jssenv
+ptyprocess==0.7.0
+    # via
+    #   pexpect
+    #   terminado
 pure-eval==0.2.3
     # via stack-data
 pycparser==2.22
@@ -431,17 +434,6 @@ python-json-logger==3.3.0
     # via jupyter-events
 pytz==2024.1
     # via pandas
-pywin32==310
-    # via
-    #   jupyter-core
-    #   plumbum
-pywin32-ctypes==0.2.3
-    # via keyring
-pywinpty==2.0.15
-    # via
-    #   jupyter-server
-    #   jupyter-server-terminals
-    #   terminado
 pyyaml==6.0.2
     # via
     #   jupyter-events