patrick/plasp
Archived
1
0
Fork 0
Code Issues 12 Releases 8 Activity

Updated readme for release 3.1.0.

Browse Source 
This adds a section about the new commands, updates out-of-date
references, and highlights the translator as the currently most
interesting component.
This commit is contained in:
Patrick Lühne 2017-11-16 18:16:55 +01:00
parent 23130134bb
commit 6889e97f47
Signed by: patrick
GPG Key ID: 05F3611E97A70ABF
3 changed files with 63 additions and 72 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

74
README.md
View File

@ -4,66 +4,72 @@
## Overview ## Overview
`plasp` 3 is in early development and not intended for productive use yet. `plasp` is a tool collection for planning in [*answer set programming*](https://en.wikipedia.org/wiki/Answer_set_programming).
`plasp` 3 supports the input languages [PDDL 3.1](https://helios.hud.ac.uk/scommv/IPC-14/software.html) (except for advanced features such as durative actions, numerical fluents, and preferences) and [SAS](http://www.fast-downward.org/TranslatorOutputFormat) (full support of SAS 3), which is used by [Fast Downward](http://www.fast-downward.org/).
`plasp` translates planning problem instances to ASP facts. The most notable tool provided by `plasp` is `plasp translate`, which translates PDDL descriptions to ASP facts.
`plasp` 3 supports the input languages [PDDL 3.1](https://helios.hud.ac.uk/scommv/IPC-14/software.html) (only basic features currently) and [SAS](http://www.fast-downward.org/TranslatorOutputFormat) (full support of SAS 3), which is used by [Fast Downward](http://www.fast-downward.org/).
Please get in touch with [Patrick Lühne](https://www.luehne.de) if you have any suggestions. ## Translating PDDL to ASP Facts
## Usage
### Translating PDDL to ASP Facts
PDDL instances are translated to ASP facts as follows: PDDL instances are translated to ASP facts as follows:
```bash ```sh
$ plasp domain.pddl problem.pddl plasp translate domain.pddl problem.pddl
``` ```
Alternatively, PDDL instances may first be translated to SAS, the output format of [Fast Downward](http://www.fast-downward.org/). Alternatively, PDDL instances may first be translated to SAS, the output format of [Fast Downward](http://www.fast-downward.org/).
```bash ```sh
$ ./fast-downward.py --translate --build=release64 domain.pddl problem.pddl ./fast-downward.py --translate --build=release64 domain.pddl problem.pddl
``` ```
This creates a file called `output.sas`, which may now be translated by `plasp`. This creates a file called `output.sas`, which may now be translated by `plasp` as well.
```bash ```sh
$ plasp output.sas plasp translate output.sas
``` ```
### Solving the Translated Instance ### Solving the Translated Instance
The translated instance can finally be solved incrementally with `clingo` and a meta encoding, for instance, [`sequential-incremental.lp`](encodings/sequential-incremental.lp): The translated instance can finally be solved incrementally with `clingo` and a meta encoding, for instance, [`sequential-incremental.lp`](encodings/sequential-incremental.lp):
```bash ```sh
$ plasp domain.pddl problem.pddl > instance.lp plasp translate domain.pddl problem.pddl > instance.lp
$ clingo encodings/sequential-incremental.lp instance.lp clingo encodings/sequential-incremental.lp instance.lp
``` ```
## Command-Line Interface ### Translator Output Format
```bash
$ plasp [options] file...
```
`plasp` automatically detects the language of the input program.
See [command-line interface](doc/command-line-interface.md) for more details.
## Output Format
`plasp` provides a uniform output format for SAS and PDDL input problems.
`plasp translate` provides a uniform output format for SAS and PDDL input problems.
See [output format](doc/output-format.md) for more details. See [output format](doc/output-format.md) for more details.
If you want to write your own meta encoding for `plasp`’s output, this [simple example encoding](encodings/sequential-incremental.lp) gets you started. If you want to write your own meta encoding for `plasp translate`’s output, this [simple example encoding](encodings/sequential-incremental.lp) gets you started.
## Provided Tools
```sh
plasp <command> [<option>...] [<input file>...]
```
Aside from translating PDDL to ASP facts, `plasp` provides the following commands:
| command | description |
|---|---|
| `translate` | Translate PDDL and SAS to ASP facts |
| `normalize` | Normalize PDDL to plasp’s custom PDDL format |
| `check-syntax` | Check the syntax of PDDL specifications |
| `beautify` | Cleanly format PDDL specifications |
| `help` | Display help message |
| `version` | Display version information |
`plasp help` shows a list of all commands provided by `plasp`.
To list all available options of a command, call `plasp <command> --help` or `plasp help <command>`.
`plasp` automatically detects the language (PDDL or SAS) of the input descriptions.
## Building ## Building
`plasp` is built via CMake and a C++ compiler. `plasp` is built with CMake and a C++ compiler.
See [building](doc/building.md) for more details. See [building](doc/building.md) for more details.
## Contributors ## Contributors

43
doc/building.md
View File

@ -2,42 +2,45 @@
`plasp` requires a C++17 compiler (preferably GCC ≥ 6.1 or clang ≥ 3.8) and CMake for building. `plasp` requires a C++17 compiler (preferably GCC ≥ 6.1 or clang ≥ 3.8) and CMake for building.
```bash ```sh
$ git clone https://github.com/potassco/plasp.git git clone https://github.com/potassco/plasp.git
$ cd plasp cd plasp
$ mkdir -p build/release mkdir -p build/release
$ cd build/release cd build/release
$ cmake ../.. -DCMAKE_BUILD_TYPE=Release cmake ../.. -DCMAKE_BUILD_TYPE=Release
$ make make
``` ```
The built `plasp` binary is then located at `plasp/build/release/bin/plasp`. The built `plasp` binary is then located at `plasp/build/release/bin/plasp`.
To update `plasp` to the most recent version, perform the following steps: To update `plasp` to the most recent version, perform the following steps:
```bash ```sh
$ cd plasp cd plasp
$ git pull git checkout master
$ cd build/release git pull
$ cmake . cd build/release
$ make cmake .
make
``` ```
## Running the Tests ## Running the Tests
`plasp` provides unit tests written using the [Catch](https://github.com/philsquared/Catch) framework. `plasp` provides unit tests written with [Catch2](https://github.com/catchorg/Catch2).
Before building and running the tests, make sure you have fetched the Catch git submodule: Before building and running the tests, make sure you have fetched the Catch submodule:
```bash ```sh
$ git submodule init git submodule init
$ git submodule update git submodule update
``` ```
Afterward, enable the flag `BUILD_TESTS` in your CMake configuration. Afterward, enable the flag `BUILD_TESTS` in your CMake configuration.
Finally, build and run the tests as follows: Finally, build and run the tests as follows:
```bash ```sh
$ make run-tests make run-tokenize-tests
make run-pddl-tests
make run-tests
``` ```
After updating `plasp`, make sure to execute CMake again in order for the tests to run correctly. After updating `plasp`, make sure to execute CMake again in order for the tests to run correctly.

18
doc/command-line-interface.md
View File

@ -1,18 +0,0 @@
# Command-Line Interface
```bash
$ plasp [options] file...
```
`plasp` automatically detects the language of the input files.
Multiple files may be provided in an arbitrary order.
The `file...` arguments may also be omitted, in which case the input is read from `std::cin`.
`plasp` supports the following options:
| **option** | **explanation** |
|------------|-----------------|
| `-l` [ `--language` ] arg (=`auto`) | Input language (`pddl`, `sas`, `auto`) |
| `--warning-level` arg (=`show`) | Show warnings (`show`), treat them as errors (`error`), or ignore them (`ignore`) |
| `--color` arg (=`auto`) | Colorize output (`always`, `never`, `auto`) |