LatPlan : A domain-independent, image-based classical planner

Use tagged versions for reliable reproduction of the results.

NEWS Updates on version 4.0: Updates for Cube-Space AE in IJCAI2020 paper.
NEWS Updates on version 4.1.3: Minor refactoring. We also released the trained weights. See Releases.
NEWS Updates on version 5: Updates for Bidirectional Cube-Space AE in JAIR paper.
- AMA3+ Cube-Space AE : A revised version of AMA3 Cube-Space AE (IJCAI20 version) which is now modeled as a sound generative model.
- AMA4+ Bidirectional Cube-Space AE : An extension of Cube-Space AE which can learn both effects and preconditions.

See older news in ./NEWS.org

This repository contains the source code of LatPlan.

Asai, Kajino, Fukunaga, Muise: 2021. Classical Planning in Deep Latent Space.
- Preprint under review in JAIR. https://arxiv.org/abs/2107.00110
Asai, M; Muise, C.: 2020. Learning Neural-Symbolic Descriptive Planning Models via Cube-Space Priors: The Voyage Home (to STRIPS).
- Accepted in IJCAI-2020 (Accept ratio 12.6%). https://arxiv.org/abs/2004.12850
Asai, M.: 2019. Neural-Symbolic Descriptive Action Model from Images: The Search for STRIPS.
- https://arxiv.org/abs/1912.05492
Asai, M.: 2019. Unsupervised Grounding of Plannable First-Order Logic Representation from Images (code available from https://github.com/guicho271828/latplan-fosae)
- Accepted in ICAPS-2019, Learning and Planning Track. https://arxiv.org/abs/1902.08093
Asai, M.; Kajino, F: 2019. Towards Stable Symbol Grounding with Zero-Suppressed State AutoEncoder
- Accepted in ICAPS-2019, Learning and Planning Track. https://arxiv.org/abs/1903.11277
Asai, M.; Fukunaga, A: 2018. Classical Planning in Deep Latent Space: Breaking the Subsymbolic-Symbolic Boundary.
- Accepted in AAAI-2018. https://arxiv.org/abs/1705.00154
Asai, M.; Fukunaga, A: 2017. Classical Planning in Deep Latent Space: From Unlabeled Images to PDDL (and back).
- In Knowledge Engineering for Planning and Scheduling (KEPS) Workshop (ICAPS2017).
- In Cognitum Workshop at ICJAI-2017.
- In Neural-Symbolic Workshop 2017.

Notes on NVIDIA port of Tensorflow

The system is built on Tensorflow 1.15. Since the official Tensorflow by Google (both the source code and the package) no longer supports 1.15, machines with recent GPUs require a port maintained by NVIDIA. Our installation script installs this port. The port only supports Linux, therefore we do not support OSX and Windows.

Setup with Anaconda / Miniconda (recommended)

anaconda / miniconda (https://docs.conda.io/en/latest/miniconda.html) is a dependency management system that can install both python and non-python dependencies into a local, encapsulated environment. It is conceptually similar to docker, but it does not use virtualization or container infrastructure. We recommend using miniconda, as it is smaller.

After the installation, run the following code:

conda config --add channels conda-forge
conda config --set channel_priority strict
source ./install.sh   # This takes about 15-30 min. Conda does not provide an informative progress, so be patient

Command Line Interface

Installing the latest version of Latplan via pip creates a runnable latplan script in ~/.local/bin. The script is not usable for running the experiments (see the next section) because it has an empty hyperparameter. However, it has the same command line API as train_common.py, train_kltune.py, and so on, therefore it may be useful for you to understand the command line API for those scripts.

(latplan) 07/05 08:08 latplan$ latplan -h
WARNING:tensorflow:Deprecation warnings have been disabled. Set TF_ENABLE_DEPRECATION_WARNINGS=1 to re-enable them.
WARNING:root:Limited tf.compat.v2.summary API due to missing TensorBoard installation.
Using TensorFlow backend.
Default float: float32
usage: latplan [-h] mode subcommand ...

positional arguments:
mode A string which contains mode substrings.
Recognized modes are:

learn : perform the training with a hyperparameter tuner. Results are stored in samples/[experiment]/logs/[hyperparameter].
If 'learn' is not specified, it attempts to load the stored weights.
plot : produce visualizations
dump : dump the csv files necessary for producing the PDDL models
summary : perform extensive performance evaluations and collect the statistics, store the result in performance.json
debug : debug training limited to epoch=2, batch_size=100. dataset is truncated to 200 samples
reproduce : train the best hyperparameter so far three times with different random seeds. store the best results.
iterate : iterate plot/dump/summary commands above over all hyperparmeters that are already trained and stored in logs/ directory.

For example, learn_plot_dump contains 'learn', 'plot', 'dump' mode.
The separater does not matter because its presense is tested by python's `in` directive, i.e., `if 'learn' in mode:` .
Therefore, learnplotdump also works.

optional arguments:
-h, --help show this help message and exit

subcommand:

A string which matches the name of one of the dataset functions in latplan.main module.

Each task has a different set of parameters, e.g.,
'puzzle' has 'type', 'width', 'height' where 'type' should be one of 'mnist', 'spider', 'mandrill', 'lenna',
while 'lightsout' has 'type' being either 'digital' and 'twisted', and 'size' being an integer.
See subcommand help.

subcommand
hanoi Tower of Hanoi.
puzzle Sliding tile puzzle.
puzzle_objs
Object-based sliding tile puzzle.
lightsout LightsOut game (see https://en.wikipedia.org/wiki/Lights_Out_(game))
sokoban Sokoban environment rendered by PDDLGym.
sokoban_objs
Object-based Sokoban environment rendered by PDDLGym.
blocks Blocksworld environment.
blocks_objs
Object-based blocksworld environment.

(latplan) 07/05 08:09 latplan$ latplan learn hanoi -h
WARNING:tensorflow:Deprecation warnings have been disabled. Set TF_ENABLE_DEPRECATION_WARNINGS=1 to re-enable them.
WARNING:root:Limited tf.compat.v2.summary API due to missing TensorBoard installation.
Using TensorFlow backend.
Default float: float32
usage: latplan mode hanoi [-h] disks towers num_examples aeclass [comment]

positional arguments:
  disks         The number of disks in the environment.
  towers        The number of towers, or the width of the environment.
  num_examples  Number of data points to use. 90% of this number is used for training, and 5% each for validation and testing. It is
                assumed that the user has already generated a dataset archive in latplan/puzzles/, which contains a larger number of
                data points using the setup-dataset script provided in the root of the repository.
  aeclass       A string which matches the name of the model class available in latplan.model module. It must be one of: AE StateAE
                ZeroSuppressStateAE VanillaTransitionAE HammingTransitionAE CosineTransitionAE PoissonTransitionAE
                ConcreteDetConditionalEffectTransitionAE ConcreteDetBoolMinMaxEffectTransitionAE
                ConcreteDetBoolSmoothMinMaxEffectTransitionAE ConcreteDetLogitAddEffectTransitionAE
                ConcreteDetLogitAddEffect2TransitionAE ConcreteDetNormalizedLogitAddEffectTransitionAE CubeSpaceAE_AMA3
                ConcreteDetNormalizedLogitAddBidirectionalTransitionAE CubeSpaceAE_AMA4 ConcreteDetLogitAddEffectTransitionAEPlus
                ConcreteDetLogitAddEffect2TransitionAEPlus ConcreteDetNormalizedLogitAddEffectTransitionAEPlus
                ConvolutionalConcreteDetNormalizedLogitAddEffectTransitionAEPlus CubeSpaceAE_AMA3Plus CubeSpaceAE_AMA3Conv
                ConcreteDetNormalizedLogitAddBidirectionalTransitionAEPlus
                ConvolutionalConcreteDetNormalizedLogitAddBidirectionalTransitionAEPlus CubeSpaceAE_AMA4Plus CubeSpaceAE_AMA4Conv
  comment       A string which is appended to the directory name to label each experiment. (default: )

optional arguments:
  -h, --help    show this help message and exit

Running

Next, customize the following files for your job scheduler before running. The job submission commands are stored in a variable $common, which by default has the value like jbsub -mem 32g -cores 1+1 -queue x86_24h, which means the jobs are submitted to a 24 hour runtime limit queue, requesting 1 cpu, 1 gpu (1+1) and 32g memory. You also need to uncomment the commands to run. By default, everything is commented out and nothing runs.

# Submit the jobs for training AMA3+ (Cube-Space AEs) and AMA4+ (Bidirectional Cube-Space AEs)
./train_propositional.sh

# Submit the jobs for converting the training results into PDDL files
./pddl-ama3.sh

# Copy the problem instances into a target directory.
problem-generators/copy propositional problem-instances-10min-0.0-1

# Edit run_ama3_all.sh to specify appropriate target directory and then submit the jobs for planning.
# To reproduce the exact same experiments in the paper,
# approximately 400 jobs are submitted. Each job requires 8 cores, no GPUs, and takes 6 hours maximum.
# Details can be customized for your compute environment.
./run_ama3_all.sh 

# After the experiments, run this to generate the tables and figures.
# for details read the source code.
make -C tables

file structure

Library code

latplan/main/*.py
Each file contains source code for loading the dataset and launching the training.

latplan/model.py
network definitions.

latplan/mixins/*.py
Contains various mixin classes used to build a complex neural network.

latplan/util/
contains general-purpose utility functions for python code.

latplan/puzzles/
code for domain generators/validators.

latplan/puzzles/*.py
each file represents a domain.

latplan/puzzles/model/*.py
the core model (successor rules etc.) of the domain. this is disentangled from the images.
Scripts

train_{common,kltune,notune,nozsae}.py
Scripts for training Latplan. Each file specifies a different set of hyperparameters.

ama{1,2}-planner.py
Latplan using AMA1/AMA2. (obsolete)

ama3-planner.py
Latplan using visual inputs (init, goal) and a PDDL domain file.

run_ama{1,2,3}_all.sh
Run all experiments.

helper/
helper scripts for AMA1.

problem-generators/
scripts for generating problem instances.

tests/: test files, mostly the unit tests for domain generator/validator
samples/: where the learned results should go. Each SAE training results are stored in a subdirectory.
tables/: code for storing experimental results into SQLITE and generating tables and figures.
(git submodule) planner-scripts/: My personal scripts for invoking domain-independent planners. Not just Fast Downward.
(git submodule) downward/: Fast Downward installation.