Browse Source

Improve doc

Arthur Bit-Monnot 5 months ago
parent
commit
a3839de2e5
5 changed files with 85 additions and 68 deletions
  1. 2
    67
      README.md
  2. 2
    0
      doc/src/SUMMARY.md
  3. 74
    0
      doc/src/entry-points.md
  4. 1
    0
      doc/src/prelude.md
  5. 6
    1
      doc/src/solvers.md

+ 2
- 67
README.md View File

@@ -19,7 +19,6 @@ To run the program in IntelliJ, you can
19 19
  - Select `Run Main.main()`. It should complain that some arguments are missing.
20 20
  - Give it the expected command line arguments : `Run > Edit Configuration`, then fill in the `Program arguments` text box.
21 21
 
22
-
23 22
 ## Working on the command line (Gradle)
24 23
 
25 24
 Compilation instructions are given for Linux. On Windows you can use the `gradlew.bat` script (but you are on your own).
@@ -44,72 +43,8 @@ This is especially useful if you want to run it on another machine.
44 43
 ❯ java -jar build/libs/JSP.jar --solver basic --instance ft06
45 44
 ```
46 45
 
47
-The command line above indicates that we want to solve the instance named`ft06` with the `basic` solver. It should give an output like the following :
48
-```
49
-                         basic
50
-instance size  best      runtime makespan ecart
51
-ft06     6x6     55            1       60   9.1
52
-AVG      -        -          1.0        -   9.1
53
-```
54 46
 
55
-Fields in the result view are the following :
56
-- `instance`: name of the instance
57
-- `size`: size of the instance `{num-jobs}x{num-tasks}`
58
-- `best`: best known resultfor this instance
59
-- `runtime`: time taken by the solver in milliseconds (rounded)
60
-- `makespan`: makespan of the solution
61
-- `ecart`: normalized distance to the best result: `100 * (makespan - best) / best` 
47
+## Documentation
62 48
 
63
-One can also specify multiple solvers (below `basic` and `random`) and instances (below `ft06`, `ft10` and `ft20`) for simultaneous testing:
64
-
65
-```
66
-❯ java -jar build/libs/JSP.jar --solver basic random --instance ft06 ft10 ft20
67
-
68
-                         basic                         random
69
-instance size  best      runtime makespan ecart        runtime makespan ecart
70
-ft06     6x6     55            1       60   9.1            999       55   0.0
71
-ft10     10x10  930            0     1319  41.8            999     1209  30.0
72
-ft20     20x5  1165            0     1672  43.5            999     1529  31.2
73
-AVG      -        -          0.3        -  31.5          999.0        -  20.4
74
-```
75
-Here the last line give the average `runtime` and `ecart` for each solver.
76
-
77
-```
78
-sage: jsp-solver [-h] [-t TIMEOUT] --solver SOLVER [SOLVER ...]
79
-                  --instance INSTANCE [INSTANCE ...]
80
-
81
-Solves jobshop problems.
82
-
83
-named arguments:
84
-  -h, --help             show this help message and exit
85
-  -t TIMEOUT, --timeout TIMEOUT
86
-                         Solver  timeout  in  seconds  for  each  instance. 
87
-                         (default: 1)
88
-  --solver SOLVER [SOLVER ...]
89
-                         Solver(s) to use  (space  separated  if  more than
90
-                         one)
91
-  --instance INSTANCE [INSTANCE ...]
92
-                         Instance(s) to  solve  (space  separated  if  more
93
-                         than one). All instances  starting  with the given
94
-                         String will be  selected.  (e.g.  "ft" will select
95
-                         the instances ft06, ft10 and ft20.
96
-```
49
+Documentation for this project is available here : [https://insa-4ir-meta-heuristiques.github.io/doc/](https://insa-4ir-meta-heuristiques.github.io/doc/)
97 50
 
98
-
99
-## IDE Support
100
-
101
-Most IDEs should provide support for importing gradle projects. However, our experience has been best with IntelliJ so far and we would recommend it.
102
-
103
-#### IntelliJ
104
-
105
-IntelliJ has worked best, with out of the box support for the import of gradle projets:
106
-https://www.jetbrains.com/help/idea/gradle.html#gradle_import_project_start
107
-
108
-
109
-#### Eclipse
110
-
111
-Most technical problems have been related to the use of Eclipse so we don't recommend using it unless you have a good reason to.
112
-We have however configured gradle to allow generating an eclipse configuration like so : 
113
-```
114
-./gradlew eclipseClean eclipse
115
-```

+ 2
- 0
doc/src/SUMMARY.md View File

@@ -1,5 +1,7 @@
1 1
 # Summary
2 2
 
3
+- [Welcome](./prelude.md)
3 4
 - [Instances](./instances.md)
4 5
 - [Encodings](./encodings.md)
5 6
 - [Solvers](./solvers.md)
7
+- [Entry Points](./entry-points.md)

+ 74
- 0
doc/src/entry-points.md View File

@@ -0,0 +1,74 @@
1
+# Entry Points
2
+
3
+
4
+## `jobshop.MainTest`
5
+
6
+This is a java main class that you can use to run some small tests. It comes with some initial code to get you started when exploring the encodings.
7
+
8
+## `jobshop.Main`
9
+
10
+This is the principal entry point that aims at helping you running many solvers on many instances and comparing the results.
11
+It expects several command line arguments to specify which solvers to run and which instance to solve.
12
+
13
+
14
+```
15
+Usage: jsp-solver [-h] [-t TIMEOUT] --solver SOLVER [SOLVER ...]
16
+                  --instance INSTANCE [INSTANCE ...]
17
+
18
+Solves jobshop problems.
19
+
20
+named arguments:
21
+  -h, --help             show this help message and exit
22
+  -t TIMEOUT, --timeout TIMEOUT
23
+                         Solver  timeout  in  seconds  for  each  instance. 
24
+                         (default: 1)
25
+  --solver SOLVER [SOLVER ...]
26
+                         Solver(s) to use  (space  separated  if  more than
27
+                         one)
28
+  --instance INSTANCE [INSTANCE ...]
29
+                         Instance(s) to  solve  (space  separated  if  more
30
+                         than one). All instances  starting  with the given
31
+                         String will be  selected.  (e.g.  "ft" will select
32
+                         the instances ft06, ft10 and ft20.
33
+```
34
+
35
+
36
+### Example usage
37
+
38
+```shell
39
+# Running the Main program with gradle
40
+❯ ./gradlew run --args="--solver basic --instance ft06"
41
+```
42
+
43
+The command line above indicates that we want to solve the instance named`ft06` with the `basic` solver. It should give an output like the following :
44
+```
45
+                         basic
46
+instance size  best      runtime makespan ecart
47
+ft06     6x6     55            1       60   9.1
48
+AVG      -        -          1.0        -   9.1
49
+```
50
+
51
+Fields in the result view are the following :
52
+- `instance`: name of the instance
53
+- `size`: size of the instance `{num-jobs}x{num-tasks}`
54
+- `best`: best known resultfor this instance
55
+- `runtime`: time taken by the solver in milliseconds (rounded)
56
+- `makespan`: makespan of the solution
57
+- `ecart`: normalized distance to the best result: `100 * (makespan - best) / best` 
58
+
59
+One can also specify multiple solvers (below `basic` and `random`) and instances (below `ft06`, `ft10` and `ft20`) for simultaneous testing:
60
+
61
+```shell
62
+❯ ./gradlew run --args="--solver basic random --instance ft06 ft10 ft20"
63
+
64
+                         basic                         random
65
+instance size  best      runtime makespan ecart        runtime makespan ecart
66
+ft06     6x6     55            1       60   9.1            999       55   0.0
67
+ft10     10x10  930            0     1319  41.8            999     1209  30.0
68
+ft20     20x5  1165            0     1672  43.5            999     1529  31.2
69
+AVG      -        -          0.3        -  31.5          999.0        -  20.4
70
+```
71
+Here the last line give the average `runtime` and `ecart` for each solver.
72
+
73
+
74
+**Tip:** When selecting instance to solve, you can only provide a prefix to instance name. All instances that start with this prefix will be selected.

+ 1
- 0
doc/src/prelude.md View File

@@ -0,0 +1 @@
1
+# Welcome

+ 6
- 1
doc/src/solvers.md View File

@@ -24,4 +24,9 @@ It repeats this process until the deadline to produce a result is met and finall
24 24
 The greddy solver is not implemented yet. 
25 25
 Its constructor accepts a parameter that specifies the priority that should be used to produce solutions.
26 26
 
27
-## Descent Solver
27
+## Descent Solver
28
+
29
+
30
+### Neighborhoods
31
+
32
+TODO

Loading…
Cancel
Save