# Manual for Running our Experiments

In this README, we explain how to use our code to reproduce the results of our experiments.

## Prerequisites

To simplify setup of the experiments, we also provide a Dockerfile.

### Setup with Docker

Simply execute

```
docker build -f ./Dockerfile -t urpils-experiments:latest .
```

to create a Dockerimage with all necessary setup for the experiments.

You can start the Docker container by
```
docker run --rm -d -p 80:80 -p 7681:7681 --name urpils urpils-experiments:latest
```

Open the browser and visit http://localhost:7681 to open a web shell in the container. Visit http://localhost for a web based file browser.

### Manual Setup without Docker

We strongly recommend using Docker to run the experiments.
If you want to setup the environment yourself for any reason,
execute the following steps:

1. Install "make"
2. Install Python 3.11
3. Create a new virtual environment by ```python311 -m venv venv```
4. Make sure to use the virtual environment
5. Install all necessary dependencies by ```pip install -r requirements.txt```
6. We use Cython to speed up parts of the code. Compile by ```make cython```
7. To make our relative imports work, set the PYTHONPATH environment variable to the project directory. Run ```export PYTHONPATH=.``` on Linux and ```set PYTHONPATH=.``` on Windows.

Optionally, compile the following dependencies which are necessary if you want to run competitors or using special options.
Parts of the experiments might work without them.
Ensure ```cmake``` and ```gcc``` are available.

```bash
make build_fast_downward
make build_metric_ff
chmod u+x ${PYTHONPATH}/thirdparties/approxmc/amd64-linux/approxmc
export LD_LIBRARY_PATH=${projectPath}/thirdparties/approxmc/amd64-linux/
chmod u+x ${PYTHONPATH}/thirdparties/meta-planning/src/meta_planning/util/planners/madagascar/M
make build_planminer
chmod u+x ${PYTHONPATH}/thirdparties/PlanMiner/bin/PlanMiner
```

## Running the Experiments of Our Paper

You can find all the commands we used for our experiments under "experiments/ca/methods/scripts.bat".

## Run UrPils on Your Own Data

If your data is from a PDDL planning problem, please use the same format as
in "thirdparties/meta-planning/src/meta_planning/dataset".
Use the parameters
```
--dataset_generator="Metaplanning(path_to_your_dataset_folder search_new_valid_actions=False)"
--method_list="['URPiLs(verbose=True,planning_dataset=True)']"
```
to run our python script "experiments/ca/methods/unsupervised_ca_benchmark.py".

In case your data is from a constraint programming dataset, implement your own dataset generator. Take the "prolothar_ca/dataset_generator/n_queens.py" file as an example. Follow the naming scheme, i.e., ensure your class ends with "CaDatasetGenerator".
Import your dataset generator in "experiments/ca/methods/unsupervised_ca_benchmark.py" and add the type to the "parse_dataset_generator" method in "experiments/cli_utils.py".
Use the parameter
```
--dataset_generator="YourDatasetGeneratorName(yourParameters)"
```
For our method, use the parameter
```
--method_list="['URPiLs(verbose=True,implication_pairs_limit=1000)'
```
The implication_pairs_limit parameter controls how many samples f_a(x) -> f_a(y) are analyzed to build the item set classification dataset to learn complex constraints. See the COMPLEX_CANDS algorithm in the paper.
If our method is too slow, you can set the parameter to "-1" to turn off this step.

## Mapping between Paper and Code

You can find the main code of URPiLs under "prolothar_ca/ca/methods/custom":
- mdl_score.pyx contains code to compute L(D|M)
- the "acquire_constraints" method in homogeneous_ca.pyx corresponds to "Algorithm 1" (URPiLs) in the paper
- the "__process_candidate_list" method in homogeneous_ca.pyx corresponds to "Algorithm 2" (Filter) in the paper
- planning_ca.pyx contains the adaption of URPiLs to AI planning
- facade.py (named after the Facade Software pattern) gives a simple interface to URPiLs

## Questions?

Feel free to write us an email to ask any questions about our method, code or experiments.