====== Assignment #1-3 - Planner ======

===== Task Definition =====
As you know, we're working towards a fully implemented planning pipeline. You modeled problems, you can create grounding of any problem and now it's time to actually solve them and generate plans. By that we mean optimal plans. Your task in the assignment 1-3 is to **implement a planner that uses the A* search algorithm** to solve PDDL problems. But what is A* search without a good heuristic? Therefore, you will implement an **optional admissible relaxation heuristic** to go with your planner. We recommend implementing h^max but the choice is yours. If you decide to implement LM-Cut, still provide the h^max value on the output. 
Your planner will be evaluated on **10 private problems**, comparing plans with the reference solution. You will be provided with 3 public problems to tune your implementation. 

===== Task Submission =====
This task is **mandatory** and you can recieve maximum of **15 points**. For every correctly solved problem you can get **1.5 points** from the automatic evaluation. 

You will implement a planner for PDDL files parsed and grounded in Python that will use the {{ :courses:pui:assignments:parser.py |given PDDL parser}} and your previously implemented grounder.py file from Assignment #1-2. 

<note important>The parser has been slightly altered since Assignment #1-2, so please download it again.</note> 

You will submit the following files into BRUTE  

  * grounder.py - file containing the implementation of your grounder in Python 
  * planner.py - file containing the implementation of your planner in Python 

The planner will be called in the following way 

<code>
python3 planner.py domain.pddl problem.pddl plan.txt
</code>

Where domain.pddl refers to the path to the domain definition, problem.pddl refers to the path to the problem definition and plan.txt will be output file where you save the generated plan.

The plan contains a sequence of actions that lead you from the initial state to a goal state. All problems have unit costs, therefore all operators' cost equals to one. Every operator has to be in parentheses containing the name of the action and its parameters. There are also two lines at the start of the file that contain the cost of the plan and the value of the **h^max heuristic for the initial state**. These two lines have to start with ';; Cost: ' and ';; Init: ' as shown in the example below. 

Example of a plan
<code>
;; Cost: 6
;; Init: 6
(pick-up b)
(stack b a)
(pick-up c)
(stack c b)
(pick-up d)
(stack d c)
</code>

===== Deadline =====
This task will be assigned during the 5. week of tutorials. You have three weeks to submit it. 

Deadline for Monday tutorials: **10.4.2023 23:59**

Deadline for Wednesday tutorials: **12.4.2023 23:59**

===== Automated Evaluation =====
Automated evaluation will be used for this task. Its main purpose is to compare plans generated by your planner to reference plans, check heuristic values for the initial states and length of the plans. The evaluation will be performed with **10 private problem domains**, each one is different. Time limit for all problem instances is **400 seconds**. Each of them shouldn't take more than 30 seconds, therefore, the limit should be more than enough. You will get **1.5 points** for every correctly solved problem. 

The automated evaluation is performed for each domain and provides you with a couple insights. It runs the KCL Validator on your plan to check if it is valid and gives you the output of the validator script. Next it check cost of your plan, compares it to the reference optimal plan cost. Then it compares the heuristic value of the initial state to the reference value. If either the plan cost or the initial heuristic are incorrect the AE will tell you the desired value. 

===== Template =====
Starting from a scratch can be difficult, so here's a short template to get you started. As usual, keep the imports of parser and grounder as they are in the template. 

<code>
import grounder
from parser import Parser
import sys 

def run_search():
    # TODO: implement the A* algorithm  
    
def print_results(): 
    # TODO: implement output print

if __name__ == '__main__':
    domain_file = sys.argv[1]
    problem_file = sys.argv[2]
    output_file = sys.argv[3]
    
    PDDL_parser = Parser()
 
    domain = PDDL_parser.parse_domain(domain_file)
    problem = PDDL_parser.parse_problem(problem_file, domain)
    
    grounded_predicates = grounder.ground_all_predicates(domain)
    grounded_actions = grounder.ground_all_actions(domain)
    
    # TODO: run search 
    # TODO: print results to file 
</code>

===== Public Data =====
To help your with debugging your code, here are three small problem instances. You have their PDDL domain and problem definitions as well as the reference solutions that were generated by A* search with the h^max heuristic. {{ :courses:pui:assignments:pddl_public_data.zip |Download them here}}. 

===== Grounder =====
To complete this assignment, you need to have grounder from Assignment #1-2. In case you were not able to submit a functional grounder for the previous assignment, you will be provided with a reference grounder you can use to complete Assignment #1-3.  

===== Validator =====
You can use the [[https://github.com/KCL-Planning/VAL|KCL Validator]] to check if your PDDLs and generated plans are valid. You can either build it yourself or use the already built one provided {{ :courses:pui:assignments:validate.zip |here}}. 

You can run the validator with 
<code>
./validate domain.pddl problem.pddl plan.txt 
</code>
where domain.pddl and problem.pddl are your input PDDL files for the planner and plan.txt is saved plan with the sequence of operators that solves the problem.