Small updates to the doc. Add a simple example

Author: kstrauch94

README.md

@@ -25,9 +25,18 @@ No further installation is necessary and the main script can be executed via fol
 python scripts/acclingo --instance_dir <directory> <optional options>
 ```
 The directory with the instances is the only required parameter, all other options are optional, see `--help` for more information.
-Per default, `acclingo` retrieves a parameter configuration optimizing runtime for solving grounded instances from the parameter space described [here](pcs/params.pcs) using instances that may be gzipped from `<directory>` .
-We provide static binaries for Linux 64 of `clingo 5.1.0` and `runsolver 3.3.4` [here](binaries/).
- 
+Per default, `acclingo` retrieves a parameter configuration optimizing runtime for solving grounded instances from the parameter space described [here](pcs/all_params.pcs) using instances that may be gzipped from `<directory>` .
+We provide static binaries for Linux 64 of `runsolver 3.3.4` [here](binaries/).
+
+# Simple Example
+This simple example assumes that you have clingo installed. In this example we optimize the solving time for the instances inside the test-domain directory. We give it a 10 second cutoff per instance and configuration pair and a total wall time of 180 seconds. Run the following command while in the main acclingo folder:
+
+```
+python scripts/acclingo --instance_dir test-domain/instances --cutoff 10 --ac_budget 180 --tae_args "{\"encoding\": \"test-domain/blocks-encoding.lp\"}"
+```
+
+When acclingo finishes running it will print out the best configuration it found. Keep in mind that this configuration might still be the base configuration given by the pcs file.
+
 # Advanced Example
 
 We provide the following example enabling algorithm configuration for instances with optimization statements.

acclingo/tae/README.md

@@ -1,6 +1,6 @@
 # Asprin TAE
 
-This TAE is very similar to the basic clasp TAE. The only differences are that it only counts a solution as a succesful solution if the optimum was found and that it needs an asprin "binary" or a way to call asprin. The penalty for no solution or no optimal solution is the maximum available time multiplied by some penalty value . This penalty value can be given as a parameter:
+This TAE is very similar to the basic clasp TAE. The only differences are that it only counts a solution as a succesful solution if the optimum was found and that it needs an asprin "binary" or a way to call asprin. The penalty for no solution or no optimal solution is the maximum available time multiplied by some penalty value. This penalty value can be given as a parameter:
 
 ⋅⋅* Parameter to penalize no optimal solution = "penalty": float
 

pcs/README.md

@@ -0,0 +1,9 @@
+## PCS files
+The pcs (parameter configuration space) files in this folder denote what parameters acclingo will try to optimize. They also denote what values each option can take.
+
+#### Parameter files for clasp
+In the all_params.pcs file all solver parameters along with their possible values are given. If a parameter has a interval of possible values then this is represented in the pcs file aswell.  The interval can be integer based, e.g. the integer interval [1,64] means that any number between 1 and 64 is a valid value for the parameter. The interval can also be composed of reals, e.g. the interval [1.0,2.0]. This means that this file has an infite number of combinations in the configuration space.
+
+The all_params_disc.pcs file has the same parameters as the all_params.pcs file. However, any parameter where there was an interval has its possible values reduced to only a couple of options. For example, instead of the interval [1,64] we now have the possible options {1,2,10,30,50,64}
+
+The limited_params.pcs file cuts down parameters of the all_params_disc.pcs file and only keeps the ones that pertain to *optimization*.

test-domain/blocks-encoding.lp

@@ -0,0 +1,39 @@
+
+time(0..horizon).
+
+action(move(B,L)) :- block(B), loc(L), B != L.
+
+
+on(B,B2,0) :- init(on(B,B2)).
+
+
+{do(A,T) : action(A)} 1 :- time(T), T>0.
+1 {on(B,L,T) : loc(L)} 1 :- block(B), time(T), T>0.
+
+clear(B,T) :- not on(B2,B,T) : block(B2), B2 != B; block(B), time(T).
+clear(table,T) :- time(T).
+
+%precondition
+:- do(move(B,L),T), not clear(L,T-1).
+:- do(move(B,L),T), not clear(B,T-1).
+
+%postcodition
+:- do(move(B,L),T), not on(B,L,T).
+%on(B,L,T) :- do(move(B,L),T).
+
+%inertia
+:- on(B,L,T), not on(B,L,T-1), not do(move(B,L),T), block(B), time(T), T>0.
+
+% cant have 2 blocks on 1 block
+:- on(B1,B,T), on(B2,B,T), B1 < B2, block(B).
+
+% cant have 1 block on 2 blocks
+:- on(B,B1,T), on(B,B2,T), B1 < B2.
+
+% block can't be on top of each other
+:- on(B1,B2,T), on(B2,B1,T).
+
+% block can't be on itself
+:- on(B,B,T), time(T).
+
+:- not on(B,L,horizon), goal(on(B,L)).

test-domain/instances/block_b20_t10_time_1.6_seed_8007.lp

@@ -0,0 +1,56 @@
+#const horizon=32.
+
+block(1..20).
+loc(table).
+loc(B) :- block(B).
+
+init(on(7,table)).
+init(on(8,table)).
+init(on(19,8)).
+init(on(16,19)).
+init(on(3,table)).
+init(on(2,table)).
+init(on(18,table)).
+init(on(11,table)).
+init(on(6,11)).
+init(on(15,table)).
+init(on(20,15)).
+init(on(5,table)).
+init(on(17,table)).
+init(on(1,17)).
+init(on(12,1)).
+init(on(4,table)).
+init(on(9,table)).
+init(on(13,table)).
+init(on(14,table)).
+init(on(10,14)).
+
+goal(on(20,table)).
+goal(on(1,20)).
+goal(on(11,1)).
+goal(on(2,11)).
+
+goal(on(12,table)).
+
+goal(on(10,table)).
+goal(on(8,10)).
+
+goal(on(7,table)).
+
+goal(on(18,table)).
+goal(on(15,18)).
+
+goal(on(14,table)).
+
+goal(on(13,table)).
+goal(on(17,13)).
+goal(on(9,17)).
+goal(on(4,9)).
+
+goal(on(16,table)).
+goal(on(3,16)).
+
+goal(on(5,table)).
+goal(on(6,5)).
+
+goal(on(19,table)).

test-domain/instances/block_b20_t1_time_1.6_seed_8007.lp

@@ -0,0 +1,47 @@
+#const horizon=32.
+
+block(1..20).
+loc(table).
+loc(B) :- block(B).
+
+init(on(2,table)).
+init(on(8,table)).
+init(on(13,8)).
+init(on(20,table)).
+init(on(18,20)).
+init(on(6,table)).
+init(on(10,table)).
+init(on(14,10)).
+init(on(12,table)).
+init(on(4,table)).
+init(on(17,4)).
+init(on(15,table)).
+init(on(5,table)).
+init(on(7,table)).
+init(on(1,7)).
+init(on(11,table)).
+init(on(16,11)).
+init(on(19,16)).
+init(on(9,19)).
+init(on(3,table)).
+
+goal(on(3,table)).
+goal(on(5,3)).
+goal(on(13,5)).
+goal(on(2,13)).
+goal(on(7,2)).
+goal(on(14,7)).
+goal(on(9,14)).
+goal(on(19,9)).
+goal(on(17,19)).
+goal(on(20,17)).
+goal(on(11,20)).
+goal(on(16,11)).
+goal(on(4,16)).
+goal(on(10,4)).
+goal(on(15,10)).
+goal(on(8,15)).
+goal(on(6,8)).
+goal(on(18,6)).
+goal(on(1,18)).
+goal(on(12,1)).

test-domain/instances/block_b20_t5_time_1.6_seed_8007.lp

@@ -0,0 +1,51 @@
+#const horizon=32.
+
+block(1..20).
+loc(table).
+loc(B) :- block(B).
+
+init(on(4,table)).
+init(on(5,4)).
+init(on(1,5)).
+init(on(9,table)).
+init(on(16,table)).
+init(on(12,table)).
+init(on(7,table)).
+init(on(17,7)).
+init(on(15,table)).
+init(on(18,15)).
+init(on(3,table)).
+init(on(10,table)).
+init(on(19,table)).
+init(on(13,19)).
+init(on(6,table)).
+init(on(8,6)).
+init(on(2,table)).
+init(on(11,table)).
+init(on(14,table)).
+init(on(20,14)).
+
+goal(on(18,table)).
+goal(on(13,18)).
+goal(on(6,13)).
+goal(on(9,6)).
+
+goal(on(1,table)).
+goal(on(5,1)).
+goal(on(8,5)).
+goal(on(10,8)).
+goal(on(12,10)).
+
+goal(on(19,table)).
+goal(on(14,19)).
+goal(on(11,14)).
+goal(on(17,11)).
+
+goal(on(7,table)).
+goal(on(3,7)).
+goal(on(2,3)).
+
+goal(on(15,table)).
+goal(on(20,15)).
+goal(on(16,20)).
+goal(on(4,16)).

test-domain/instances/block_b30_t10_time_1.6_seed_8007.lp

@@ -0,0 +1,76 @@
+#const horizon=48.
+
+block(1..30).
+loc(table).
+loc(B) :- block(B).
+
+init(on(23,table)).
+init(on(5,23)).
+init(on(12,table)).
+init(on(15,12)).
+init(on(17,table)).
+init(on(6,17)).
+init(on(21,6)).
+init(on(20,21)).
+init(on(10,table)).
+init(on(11,10)).
+init(on(9,11)).
+init(on(4,table)).
+init(on(29,table)).
+init(on(7,29)).
+init(on(22,table)).
+init(on(27,table)).
+init(on(28,27)).
+init(on(8,28)).
+init(on(16,8)).
+init(on(13,table)).
+init(on(25,table)).
+init(on(30,table)).
+init(on(3,30)).
+init(on(14,3)).
+init(on(1,table)).
+init(on(19,table)).
+init(on(24,19)).
+init(on(26,24)).
+init(on(2,table)).
+init(on(18,table)).
+
+goal(on(16,table)).
+
+goal(on(10,table)).
+goal(on(28,10)).
+goal(on(5,28)).
+goal(on(20,5)).
+
+goal(on(7,table)).
+goal(on(1,7)).
+goal(on(14,1)).
+goal(on(13,14)).
+goal(on(4,13)).
+
+goal(on(9,table)).
+goal(on(29,9)).
+
+goal(on(23,table)).
+goal(on(15,23)).
+goal(on(18,15)).
+
+goal(on(26,table)).
+goal(on(8,26)).
+
+goal(on(30,table)).
+goal(on(21,30)).
+goal(on(12,21)).
+
+goal(on(27,table)).
+
+goal(on(22,table)).
+goal(on(24,22)).
+goal(on(3,24)).
+goal(on(25,3)).
+goal(on(19,25)).
+
+goal(on(6,table)).
+goal(on(11,6)).
+goal(on(2,11)).
+goal(on(17,2)).

test-domain/instances/block_b30_t1_time_1.6_seed_8007.lp

@@ -0,0 +1,67 @@
+#const horizon=48.
+
+block(1..30).
+loc(table).
+loc(B) :- block(B).
+
+init(on(22,table)).
+init(on(11,table)).
+init(on(12,table)).
+init(on(28,12)).
+init(on(20,table)).
+init(on(15,table)).
+init(on(25,15)).
+init(on(9,25)).
+init(on(6,9)).
+init(on(13,table)).
+init(on(4,table)).
+init(on(16,table)).
+init(on(5,table)).
+init(on(21,table)).
+init(on(19,21)).
+init(on(2,table)).
+init(on(27,2)).
+init(on(7,table)).
+init(on(1,7)).
+init(on(3,1)).
+init(on(29,table)).
+init(on(30,table)).
+init(on(23,30)).
+init(on(10,23)).
+init(on(17,10)).
+init(on(8,table)).
+init(on(14,table)).
+init(on(26,table)).
+init(on(24,table)).
+init(on(18,table)).
+
+goal(on(29,table)).
+goal(on(1,29)).
+goal(on(16,1)).
+goal(on(6,16)).
+goal(on(25,6)).
+goal(on(22,25)).
+goal(on(5,22)).
+goal(on(10,5)).
+goal(on(27,10)).
+goal(on(26,27)).
+goal(on(3,26)).
+goal(on(2,3)).
+goal(on(20,2)).
+goal(on(18,20)).
+goal(on(11,18)).
+goal(on(30,11)).
+goal(on(8,30)).
+goal(on(7,8)).
+goal(on(17,7)).
+goal(on(19,17)).
+goal(on(4,19)).
+goal(on(24,4)).
+goal(on(15,24)).
+goal(on(23,15)).
+goal(on(21,23)).
+goal(on(28,21)).
+goal(on(9,28)).
+goal(on(13,9)).
+goal(on(12,13)).
+goal(on(14,12)).