Updated readme for release 3.1.0.
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:
parent
23130134bb
commit
6889e97f47
GPG Key ID:
05F3611E97A70ABF
74
README.md
74
README.md
@ -4,66 +4,72 @@
|
||||
|
||||
## 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.
|
||||
`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/).
|
||||
The most notable tool provided by `plasp` is `plasp translate`, which translates PDDL descriptions to ASP facts.
|
||||
|
||||
Please get in touch with [Patrick Lühne](https://www.luehne.de) if you have any suggestions.
|
||||
|
||||
## Usage
|
||||
|
||||
### Translating PDDL to ASP Facts
|
||||
## Translating PDDL to ASP Facts
|
||||
|
||||
PDDL instances are translated to ASP facts as follows:
|
||||
|
||||
```bash
|
||||
$ plasp domain.pddl problem.pddl
|
||||
```sh
|
||||
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/).
|
||||
|
||||
```bash
|
||||
$ ./fast-downward.py --translate --build=release64 domain.pddl problem.pddl
|
||||
```sh
|
||||
./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
|
||||
$ plasp output.sas
|
||||
```sh
|
||||
plasp translate output.sas
|
||||
```
|
||||
|
||||
### 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):
|
||||
|
||||
```bash
|
||||
$ plasp domain.pddl problem.pddl > instance.lp
|
||||
$ clingo encodings/sequential-incremental.lp instance.lp
|
||||
```sh
|
||||
plasp translate domain.pddl problem.pddl > instance.lp
|
||||
clingo encodings/sequential-incremental.lp instance.lp
|
||||
```
|
||||
|
||||
## Command-Line Interface
|
||||
|
||||
```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.
|
||||
### Translator Output Format
|
||||
|
||||
`plasp translate` provides a uniform output format for SAS and PDDL input problems.
|
||||
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
|
||||
|
||||
`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.
|
||||
|
||||
## Contributors
|
||||
|
||||
@ -2,42 +2,45 @@
|
||||
|
||||
`plasp` requires a C++17 compiler (preferably GCC ≥ 6.1 or clang ≥ 3.8) and CMake for building.
|
||||
|
||||
```bash
|
||||
$ git clone https://github.com/potassco/plasp.git
|
||||
$ cd plasp
|
||||
$ mkdir -p build/release
|
||||
$ cd build/release
|
||||
$ cmake ../.. -DCMAKE_BUILD_TYPE=Release
|
||||
$ make
|
||||
```sh
|
||||
git clone https://github.com/potassco/plasp.git
|
||||
cd plasp
|
||||
mkdir -p build/release
|
||||
cd build/release
|
||||
cmake ../.. -DCMAKE_BUILD_TYPE=Release
|
||||
make
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
```bash
|
||||
$ cd plasp
|
||||
$ git pull
|
||||
$ cd build/release
|
||||
$ cmake .
|
||||
$ make
|
||||
```sh
|
||||
cd plasp
|
||||
git checkout master
|
||||
git pull
|
||||
cd build/release
|
||||
cmake .
|
||||
make
|
||||
```
|
||||
|
||||
## Running the Tests
|
||||
|
||||
`plasp` provides unit tests written using the [Catch](https://github.com/philsquared/Catch) framework.
|
||||
Before building and running the tests, make sure you have fetched the Catch git submodule:
|
||||
`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 submodule:
|
||||
|
||||
```bash
|
||||
$ git submodule init
|
||||
$ git submodule update
|
||||
```sh
|
||||
git submodule init
|
||||
git submodule update
|
||||
```
|
||||
|
||||
Afterward, enable the flag `BUILD_TESTS` in your CMake configuration.
|
||||
Finally, build and run the tests as follows:
|
||||
|
||||
```bash
|
||||
$ make run-tests
|
||||
```sh
|
||||
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.
|
||||
|
||||
@ -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`) |
|
||||
Reference in New Issue
Block a user