====== Assignment #1 – PDDL ======
===== Problem 'simcity' =====
[[courses:a4m36pah:assignments:map.svg|{{:courses:a4m36pah:assignments:map_graph.png}}]]

The problem is to find a 'day plan' for a set of people in a city (or state, or some other geographical location). Each person has somewhere to live, where he or she starts and must end, moreover, each person has a workplace where he or she has to work. Some people may be related, i.e. a family.

The city is represented as a set of locations of interest and a multimodal graph connecting some of the locations by various modes of transport (e.g. walk, car, taxi, underground,..). There are particular vehicles providing the transport.

Each vehicle must have a driver to operate. Not all people can board all vehicles, for example a car is owned by a single family and other people cannot board it, a child cannot board a taxi (at least on its own). Being a driver of a taxi or public transport counts as a work (with no particular workplace).

===== Problem 'simcity' levels =====

There are multiple levels of complexity of the problem. The basic level is the minimal mandatory level in order to pass the assignment, for solving each of the higher levels you will receive additional points.

  - Level: basic
    * The basic problem description, some walk-only edges, at least one car, at least one on-demand transport vehicle (taxi) and at least one public transport vehicle.
  - Level: costs
    * Add costs to the problem.
    * The costs should be based on the (approximately) real distances.
    * There should be a cost of boarding a vehicle (i.e. buying a ticket) and riding a vehicle (per km). Not all vehicles have both costs.
    * Try at additional type of cost for extra point (e.g. money, time, CO2 footprint, ...)
  - Level: temporal
    * Change actions to durative/temporal
    * At least for the "drive" actions
    * You may use a smaller problem
  - Level: extended
    * Add some of the following extensions (either with or without costs):
    * Capacity - some of the vehicles (e.g. car) have limited capacity (use either STRIPS or functions)
    * Leave vs. park - there is a difference between passenger leaving a vehicle and the driver leaving a vehicle (it has to be parked) - some vehicles can park only at some locations.
    * Fuel - some of the vehicles have some fuel levels and have to be refueled to prevent running out of fuel (use either STRIPS or functions)
    * Come up with your own (non-trivial) enhancement


===== Task =====
:!: = mandatory
  - :!: Formalize problem **simcity** in PDDL language
    - Create one domain and two problems (small ~10 nodes and ~10 people and large >10 nodes and >10 people) for each problem level you model. 
    - Run a selected planner on each of the problems (may be different planner for each case)
    - Include the log and resulting plan in the deliverable
  - Evaluate 3 selected planners on a single level of the **simcity** problem (optional).
    - Run all of the selected planners on both problems of the selected domain
    - Select at least one optimal planner (that is //fd-ms//, //fd-lmcut// and //symba//)
    - Plot comparison of the planners (include in the report): time and quality (cost).
  - Create a PDF report, which will contain the following:
    * :!: description of the transport graph (ideally a picture) and the people (brief)
    * :!: specify which problem levels and features were formalized (describe your own enhancements in-detail)
    * :!: brief description of used predicates, operators and functions
    * :!: list of the selected planners (at least which were used to evaluate each problem)
    * parameters of the testing environment (native/virtual, OS, CPU, memory size)
    * execution time graphs (comparison of execution times of planners on individual instances)
    * solution quality graph (comparison of the best cost found plans on all instances)
      * Note that some of the planners (e.g. lama) finds multiple solutions - take the first for the time graph and the last (which should be the best) for the quality graph
    * conclusion 
      * comparison and evaluation of the planners (execution time, solution quality) based on the measured quality
      * comparison of the various problem levels in terms of complexity (informal) based on the results



===== Deliverable =====
  * deadline: **10. 4. 2017, 6:00**
  * 0 pts deadline: **17. 4. 2017, 6:00**
  * [[https://cw.felk.cvut.cz/upload/|CW Upload system]]
    * time spent on the assigment in hours is required
  * file **name-surname_uloha1.zip**, which contains PDF report, domain and 2 problems for each level, a log file and file(s) with a solution for every problem. The zip file should have the following structure:<code>
name-surname_uloha1.zip
|- report.pdf
|- simple
|  |- domain.pddl
|  |- p01.pddl
|  |- p02.pddl
|  |- planner1
|     |- p01.log
|     |- p01.solution
|     |- …
|  |- …
|- costs
|  |- domain.pddl
|  |- p01.pddl
|  |- p02.pddl
|  |- planner1
|     |- p01.log
|     |- p01.solution
|     |- …
|  |- …
|- temporal
|  |- domain.pddl
|  |- p01.pddl
|  |- p02.pddl
|  |- planner1
|     |- p01.log
|     |- p01.solution
|     |- …
|  |- …
|- extended
|  |- domain.pddl
|  |- p01.pddl
|  |- p02.pddl
|  |- planner1
|     |- p01.log
|     |- p01.solution
|     |- …
|  |- …
</code>
 
  * The evaluation is manual

===== Evaluation =====

| Feature | Points | Mandatory |
| Basic | 4 | :!: |
| Costs | 2-3 | |
| Temporal | 2-3 | |
| Extended: Capacity | 1-3 | |
| Extended: Leave vs. Park | 1 | |
| Extended: Fuel | 1-3 | |
| Extended: Custom | 1-3 | |
| Experiments | 2 | |
| Report | 1-3 | :!: |
| Total | 5-20 | |

  * Extended - you may choose up to 2 extensions
  * Some of the points are decided based on the quality or complexity of the solutions
  * The evaluation is done manually
 
==== Automatic evaluation ====
  * There is an automatic evaluation script at courseware (running planners on the provided domains and problems).
  * Point assignment will be done manually by me. The results from AE serve only as an input.

===== Downloads =====
  *  Solution template {{:courses:a4m36pah:assignments:simcity.zip|[download]}} [fixed 3. 3. 9:40]
    * Prepared folder structure
    * Prepared script for running the planners easily
      * usage: plan <ff|fd-fdss|fd-ms|fd-lmcut|lama|mercury|probe|symba|yahsp3> <simple|cost|complex> <p01|p02> <timeout(e.g. '10m')>
  * Planners {{:courses:a4m36pah:assignments:PAH.zip|[32bit]}} {{:courses:a4m36pah:assignments:planners64.zip|[64bit]}}
    * Sources
    * Compiled binaries (on Ubuntu 12.10, 64bit)
    * Scripts

===== Workspace Options =====
  - Use the online editor: [[http://editor.planning.domains| PDDL Editor]]
     * [[http://editor.planning.domains|PDDL editor]]
     * Default timeout 10s
     * To run a particular planner (timeout 15 min., 500MB memory limit):
       * In Solve/Custom Planner URL put: http://fornix.felk.cvut.cz:5000/[planner] where planner = 
       * ff - FF planner
       * siw - LAPKT siw-then-bfsf configuration
       * lama - LAMA planner
       * mercury - mercury planner
       * probe - probe planner
       * yahsp3 - yahsp planner
       * ms - A* with Merge&Shring heuristic (optimal)
       * lmcut - A* with LM-Cut heuristic (optimal)
       * symba - symba planner (optimal)
       * metricff - numeric variant of FF (numeric)
    * To run a numeric/temporal planner (OPTIC), use: http://fornix.felk.cvut.cz:5001 or http://temporal-solver.herokuapp.com
    * Important :!:
       * The planners are running on a single computer, do not overload it!
       * The timeout is 15min, nothing may happen during that time (and it is ok)
       * The server was not tested for high-load, this is a pilot use, please try to distribute your work throughout the time.
       * In case of any problems, contact me: [[email:michal.stolba@agents.fel.cvut.cz|Michal Štolba]]
  - Use installed planners (/opt/PAH) in the room KN:E-310 when there is no tutorial (cf. [[https://www.fel.cvut.cz/cz/education/rozvrhy-ng.B142/public/cz/mistnosti/10/12/m10123104.html|timetable]]) 
      * It is not possible to logon remotely via ssh.
      * The numeric/temporal planner optic is not installed
  - Download compiled binaries {{:courses:a4m36pah:assignments:PAH.zip|[32bit]}} {{:courses:a4m36pah:assignments:planners64.zip|[64bit]}}
      * use them on your Unix machine
      * use a virtual [[http://www.osboxes.org/ubuntu/|Ubuntu 12.10 64bit]] on [[https://www.virtualbox.org/wiki/Downloads|VirtualBox]]
  - Download and run the nodejs server locally
      * From the original repository: {{https://bitbucket.org/planning-researchers/cloud-solver|cloud solver}} 
        * (runs only siw)
      * And/or the temporal variant: {{https://bitbucket.org/haz/temporal-solver|temporal solver}} 
        * (runs only optic)
      * Or download a modified variant which can run multiple planners: {{:courses:a4m36pah:assignments:cloud.zip|cloud solvers}} {{:courses:a4m36pah:assignments:temporal.zip|temporal solver}}
        * Put it in the planners directory (containing the compiled planners)
        * Can run all planners as on the fornix machine (usage: http://localhost:5000/[planner] or http://localhost:5001 for temporal variant)
   - Donload and install image for Docker {{https://github.com/racinmat/PDDL-docker/blob/master/README.md|Planners for Docker}} and use with PDDL Editor

===== Planners and PDDL Features =====
| | ff | siw | lama | mercury | probe | yahsp3 | ms | lmcut | symba | optic | metricff |
| parse costs without numeric expressions (*,+,...) | ✘ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | 
| parse costs with numeric expressions (*,+,...)    | ✘ | ✘ | ✘ | ✘ | ✘ | ✘ | ✘ | ✘ | ✘ | ✔ | ✔ | 
| optimize for costs                                | ✘ | ✘ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✘ | ✔ |
| optimal                                           | ✘ | ✘ | ✘ | ✘ | ✘ | ✘ | ✔ | ✔ | ✔ | ✘ | ✘ |
| numeric expressions (*,+,...) in precond. and eff.| ✘ | ✘ | ✘ | ✘ | ✘ | ✘ | ✘ | ✘ | ✘ | ✔ | ✔ |
| temporal                                          | ✘ | ✘ | ✘ | ✘ | ✘ | ✘ | ✘ | ✘ | ✘ | ✔ | ✘ |
===== FAQ & Hints =====
  * Resources you can consult: 
    * [[http://ipc.informatik.uni-freiburg.de/PddlResources|Formal definitions of all PDDL versions (papers)]]
    * [[http://users.cecs.anu.edu.au/~patrik/pddlman/writing.html|Writing PDDL guide by Patrik Haslum]]
    * [[http://www.cs.toronto.edu/~sheila/2542/f10/A1/introtopddl2.pdf|Introduction to PDDL by Malte Helmert (presentation)]]
    * [[http://en.wikipedia.org/wiki/Planning_Domain_Definition_Language|PDDL (good overview of different versions)]]
  * PDDL is not case sensitive, make sure you do not name two objects i.e. a and A
  * The predicates are not reflexive by default, i.e. both ''(path A B)'' and ''(path B A)'' must be specified
  * Although valid PDDL, arithmetic constructs in cost such as ''(increase (total-cost) (* (distance ?f ?t) (cost-per-km)))'' are not supported by most of the planners
  * Best information about the errors in domain/problem files gives the ff and yahsp3 planners
  * In tutorials/logistics-example.zip is the simple logistics example in PDDL