Initial commit of codebase as of 2021-04-19

README.md

@@ -1,13 +1,40 @@
 # STRIPS-HGN
-**Update - 21st Sept 2020**: the implementation is ready but just needs some final cleaning up and testing. Due to work and other circumstances I have been unable to spend much time on research. I hope to release update this repository by [ICAPS](https://icaps20.icaps-conference.org/) (October 19-30). For those who want a copy of the code in the meantime please email me. 
+STRIPS-HGN is a framework for learning domain-independent planning heuristics completely from scratch using the hypergraph induced by the delete-relaxation of a STRIPS problem. 
 
-**Update - 21st June 2020**: our re-implementation of STRIPS-HGN is almost ready to go and is currently undergoing testing and experiments. We intend to make it available before the end of June. 
+For any issues please contact the authors of the paper. You can find our emails in the [paper](https://shen.nz/papers/shen-stripshgn-20.pdf).
 
-STRIPS-HGN is a framework for learning domain-independent planning heuristics completely from scratch using the hypergraph induced by the delete-relaxation of a STRIPS problem. 
+## Usage
+### Directory Structure
+- `benchmarks`: contains the PDDL domain and problems
+- `experiments`: the experiments used in the paper as Python scripts
+- `scripts`: helpful scripts used to run experiments on AWS. The `scripts/ec2_setup.sh` script could give hints to installing and running STRIPS-HGN
+- `src`
+  - `hypergraph_nets`: Hypergraph Networks implementation based off [Graph Networks](https://github.com/deepmind/graph_nets). Note this implementation is sub-optimal and can be improved.
+  - `strips_hgn`: logic for setting up, running and collecting results for the experiments. Includes hypergraph generation, feature mapping, generating training data, etc.
+- `tests`: some unit tests
+
+### Dependencies
+- You will need Python 3.6+
+- Use pip to install the requirements in `requirements.txt` (`pip install -r requirements.txt`)
+- Clone my custom version of Fast Downward (https://github.com/williamshen-nz/fast_downward.git) which you will need to build (use `build.py`)
 
-The code for STRIPS-HGN will be made available in the coming months.
+I would recommend using a virtual environment. The entry point for training is `src/train.py` and for evaluation is `src/eval.py`. Use the help flag (`-h, --help`) to get usage information.
 
-Please contact `william.w.y.shen at gmail.com` if the code is still not available at the end of June 2020.
+## Known Issues and TODOs
+1. Move evaluation platform to Fast Downward (this is already completed and working in a separate repository)
+2. Move remaining experiment scripts from old codebase
+   - Hanoi
+   - Matching Blocksworld
+   - Sokoban
+   - Domain-Independent Experiments
+3. Optimise Hypergraph Networks
+
+### Past Updates
+**Update - 19th April 2021**: apologies for the delay. Unfortunately, I have not had time to work on research so I am releasing the code-base as is. 
+
+**Update - 21st Sept 2020**: the implementation is ready but just needs some final cleaning up and testing. Due to work and other circumstances I have been unable to spend much time on research. I hope to release update this repository by [ICAPS](https://icaps20.icaps-conference.org/) (October 19-30). For those who want a copy of the code in the meantime please email me. 
+
+**Update - 21st June 2020**: our re-implementation of STRIPS-HGN is almost ready to go and is currently undergoing testing and experiments. We intend to make it available before the end of June. 
 
 ___
 

benchmarks/blocks-slaney/README

@@ -0,0 +1,8 @@
+Problems generated using John Slaney's Blocksworld Script
+http://users.cecs.anu.edu.au/~jks/cgi-bin/bwstates/bwcgi
+
+python gen_problems.py <problems_dir>
+will parse the large PDDL dump the script gives and separate
+it into each file
+
+All problems with 4 blocks or more are guaranteed to be unique here.