[[./img/latplanlogo-simple.svg.png]]

• 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 [[https://github.com/guicho271828/latplan/releases][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][./NEWS.org]]

[[https://travis-ci.org/guicho271828/latplan][https://travis-ci.org/guicho271828/latplan.svg?branch=master]]

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 [[https://developer.nvidia.com/blog/accelerating-tensorflow-on-a100-gpus/][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:

+begin_src sh

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

+end_src>

• 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.

+begin_src

(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.

+end_src

+begin_src

(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

+end_src

• 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.

+begin_src sh

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

+end_src

** 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.

** Gallery

[[./img/hanoi_4_3_36_81_conv_blind_path_0.png]] [[./img/lightsout_digital_4_36_20000_conv_Astar_path_0.png]] [[./img/lightsout_twisted_4_36_20000_conv_Astar_path_0.png]] [[./img/puzzle_mandrill_3_3_36_20000_conv_blind_path_0.png]] [[./img/puzzle_mnist_3_3_36_20000_conv_blind_path_0.png]] [[./img/puzzle_spider_3_3_36_20000_conv_blind_path_0.png]]