Differences between revisions 13 and 23 (spanning 10 versions)
⇤ ← Revision 13 as of 2020-07-08 13:25:11 →
Size: 3204
Editor: FlorianPommerening
Comment: Let the second section refer to the first instead of the other way around. Also the convention for the extension of singularity image files settled on "sif".
← Revision 23 as of 2023-10-12 12:30:20 → ⇥
Size: 4744
Editor: GabiRoeger
Comment: Update links
Deletions are marked like this. Additions are marked like this.
Line 5: Line 5:
Starting with Fast Downward 19.06, we release the planner in four flavours: tarball, Singularity, Docker and Vagrant.
We provide below a few instructions to get you started as quickly as possible, but you can find a more detailed description on [[ObtainingAndRunningFastDownward]] and [[PlannerUsage]].		 Fast Downward is released in four flavours: tarball, Apptainer (formerly known as Singularity), Docker and Vagrant.
Here we provide instructions to get you started as quickly as possible. You can find more usage information at [[PlannerUsage]].
Line 10: Line 10:
 * '''running experiments''': We recommend Singularity or the tarball. Docker is an alternative, but be mindful of its significant overhead.  * '''running experiments''': We recommend Apptainer or the tarball. Docker is an alternative, but be mindful of its significant overhead.
Line 15: Line 15:
== Running the Singularity image == == Running the Apptainer image ==
Line 17: Line 17:
Let us assume that you have [[https://www.sylabs.io/guides/3.5/user-guide/quick_start.html#quick-installation-steps|Singularity]] installed on your machine (we have tested this with Singularity 2.6, 3.2, and 3.5), and want to solve a planning problem located in the `$BENCHMARKS` directory. You can run run the ''satisficing'' LAMA configuration of the planner: We have tested Apptainer 1.2.2. If Apptainer isn't installed on your machine, check the following section.

To download the Fast Downward image, run:
Line 20: Line 22:
singularity pull --name downward.sif shub://aibasel/downward
singularity run downward.sif --alias lama-first $BENCHMARKS/gripper/prob01.pddl		 apptainer pull fast-downward.sif docker://aibasel/downward:latest
Line 24: Line 25:
The first command downloads the Singularity image into the local file `downward.sif`, while the second command is the one running Fast Downward from this image.
Unlike Docker, `$BENCHMARKS` does not have to be an absolute path.		 Then run the planner. The example uses the LAMA-first configuration to solve a planning task located in the `$BENCHMARKS` directory. LAMA-first is designed to find solutions quickly without much regard for plan cost:
Line 27: Line 27:
{{{#!highlight bash
./fast-downward.sif --alias lama-first $BENCHMARKS/gripper/prob01.pddl
}}}

Unlike Docker (see below), `$BENCHMARKS` does not have to be an absolute path.

=== Installing Apptainer ===

Apptainer's predecessor, Singularity, used to be shipped with Ubuntu Linux for some time, making its installation very convenient. As of this writing, this is no longer the case, but Ubuntu (deb) packages are available from the Apptainer developers. For a typical Ubuntu system, download the AMD64 deb package from https://github.com/apptainer/apptainer/releases and install it like so (example for Apptainer 1.2.2):

{{{#!highlight bash
sudo apt install ./apptainer_1.2.2_amd64.deb
}}}
Line 30: Line 43:
Let us assume that you have [[https://docs.docker.com/install/|Docker]] installed on your machine and want to solve a planning problem located on the `$BENCHMARKS` directory.
You can run the same LAMA configuration as before:		 We assume that [[https://docs.docker.com/get-docker/|Docker]] is installed on your machine. You want to solve a planning problem located on the `$BENCHMARKS` directory.
You can run the same LAMA-first configuration as before:
Line 34: Line 47:
docker run --rm -v $BENCHMARKS:/benchmarks aibasel/downward --alias lama-first /benchmarks/gripper/prob01.pddl sudo docker run --rm -v $BENCHMARKS:/benchmarks aibasel/downward --alias lama-first /benchmarks/gripper/prob01.pddl
Line 37: Line 50:
Note the use of `sudo` (Docker usually requires root privileges).
Line 38: Line 53:
containerized planner reads the problems from.
The path stored in the `$BENCHMARKS` variable needs to be absolute.		 containerized planner looks for the problem.
The path stored in the `$BENCHMARKS` variable must be absolute.
Line 41: Line 56:
The Docker image for Fast Downward is installed on your machine as a side-effect of the command.
Line 44: Line 60:
Assuming that you have [[https://www.vagrantup.com/|Vagrant]] installed on your machine, you can use the Fast Downward Vagrantfile as follows: We assume that
 * [[https://www.vagrantup.com/|Vagrant]] is installed on your machine
 * The current directory contains the Fast Downward `Vagrantfile` for the desired [[Releases|release]], the PDDL files `domain.pddl` and `problem.pddl` for the planning task you want to solve.
 * The !SoPlex LP solver is included automatically. If you want to also use the CPLEX LP solver within the planner, its installer file must be present in the directory `/path/to/lp/installers`. As of Fast Downward 23.06, you will need CPLEX 22.1.1 (installer filename `cplex_studio2211.linux-x86-64.bin`).
 * You want to create your Vagrant VM as subdirectory `my-fast-downward-vm` of the current directory. The subdirectory does not exist yet.
Line 46: Line 66:
 * Place the Vagrantfile for the desired [[Releases|release]] into some empty directory.
 * Put your PDDL files into the same directory as the Vagrantfile, say, under names `domain.pddl` and `problem.pddl`.
 * Navigate to this directory and type `vagrant up`.
 * Log into the Vagrant virtual machine by typing `vagrant ssh`.
 * Run `downward/fast-downward.py --alias lama-first /vagrant/domain.pddl /vagrant/problem.pddl`.
 * Type `exit` to leave the virtual machine, then `vagrant halt` to stop it.		 Create and provision your virtual machine as follows:
{{{#!highlight bash
# Set up the VM. Only run this one.
mkdir my-fast-downward-vm
cp Vagrantfile my-fast-downward-vm/
cp domain.pddl problem.pddl my-fast-downward-vm/
# Skip next line if you don't need LP support.
export DOWNWARD_LP_INSTALLERS=/path/to/lp/installers
cd my-fast-downward-vm
vagrant up
# The VM is now set up.
# You can now safely delete the LP installers and unset the environment variable.

# Log into the VM and run the planner.
vagrant ssh
downward/fast-downward.py --alias lama-first /vagrant/domain.pddl /vagrant/problem.pddl

# Log out from the VM.
exit
}}}
Line 55: Line 89:
See ObtainingAndRunningFastDownward for a complete description on how to build the planner from source. See the [[https://github.com/aibasel/downward/blob/main/BUILD.md|build instructions]] for a complete description on how to build the planner from source.
We recommend using the [[Releases|latest release]], especially for scientific experiments.
If you are using the main branch instead, be aware that things can break or degrade with every commit.
Line 60: Line 96:
 * Read about recommended [[ScriptUsage|experiment setups]].
 * Go through the full [[../|Documentation]].		  * Read about recommended [[https://github.com/aibasel/downward#scientific-experiments|experiment setups]].
 * Go through the full [[HomePage|Documentation]].

Back to the HomePage.

Quick start

Fast Downward is released in four flavours: tarball, Apptainer (formerly known as Singularity), Docker and Vagrant. Here we provide instructions to get you started as quickly as possible. You can find more usage information at PlannerUsage.

What flavour is for me?

  • running experiments: We recommend Apptainer or the tarball. Docker is an alternative, but be mindful of its significant overhead.

  • teaching: We recommend Vagrant.

  • development: We recommend working on a clone of the master repository.

See WhatFlavourIsForMe for a more detailed discussion.

Running the Apptainer image

We have tested Apptainer 1.2.2. If Apptainer isn't installed on your machine, check the following section.

To download the Fast Downward image, run: 

   1 apptainer pull fast-downward.sif docker://aibasel/downward:latest

Then run the planner. The example uses the LAMA-first configuration to solve a planning task located in the $BENCHMARKS directory. LAMA-first is designed to find solutions quickly without much regard for plan cost: 

   1 ./fast-downward.sif --alias lama-first $BENCHMARKS/gripper/prob01.pddl

Unlike Docker (see below), $BENCHMARKS does not have to be an absolute path.

Installing Apptainer

Apptainer's predecessor, Singularity, used to be shipped with Ubuntu Linux for some time, making its installation very convenient. As of this writing, this is no longer the case, but Ubuntu (deb) packages are available from the Apptainer developers. For a typical Ubuntu system, download the AMD64 deb package from https://github.com/apptainer/apptainer/releases and install it like so (example for Apptainer 1.2.2): 

   1 sudo apt install ./apptainer_1.2.2_amd64.deb

Running the Docker image

We assume that Docker is installed on your machine. You want to solve a planning problem located on the $BENCHMARKS directory. You can run the same LAMA-first configuration as before: 

   1 sudo docker run --rm -v $BENCHMARKS:/benchmarks aibasel/downward --alias lama-first /benchmarks/gripper/prob01.pddl

Note the use of sudo (Docker usually requires root privileges).

Note that this mounts the local directory $BENCHMARKS of your host machine under the container directory /benchmarks, which is the place where the containerized planner looks for the problem. The path stored in the $BENCHMARKS variable must be absolute.

The Docker image for Fast Downward is installed on your machine as a side-effect of the command.

Using a Vagrant machine

We assume that

  • Vagrant is installed on your machine

  • The current directory contains the Fast Downward Vagrantfile for the desired release, the PDDL files domain.pddl and problem.pddl for the planning task you want to solve.

  • The SoPlex LP solver is included automatically. If you want to also use the CPLEX LP solver within the planner, its installer file must be present in the directory /path/to/lp/installers. As of Fast Downward 23.06, you will need CPLEX 22.1.1 (installer filename cplex_studio2211.linux-x86-64.bin).

  • You want to create your Vagrant VM as subdirectory my-fast-downward-vm of the current directory. The subdirectory does not exist yet.

Create and provision your virtual machine as follows: 

   1 # Set up the VM. Only run this one.
   2 mkdir my-fast-downward-vm
   3 cp Vagrantfile my-fast-downward-vm/
   4 cp domain.pddl problem.pddl my-fast-downward-vm/
   5 # Skip next line if you don't need LP support.
   6 export DOWNWARD_LP_INSTALLERS=/path/to/lp/installers
   7 cd my-fast-downward-vm
   8 vagrant up
   9 # The VM is now set up.
  10 # You can now safely delete the LP installers and unset the environment variable.
  11 
  12 # Log into the VM and run the planner.
  13 vagrant ssh
  14 downward/fast-downward.py --alias lama-first /vagrant/domain.pddl /vagrant/problem.pddl
  15 
  16 # Log out from the VM.
  17 exit

Source code

See the build instructions for a complete description on how to build the planner from source. We recommend using the latest release, especially for scientific experiments. If you are using the main branch instead, be aware that things can break or degrade with every commit.

Next steps

FastDownward: QuickStart (last edited 2023-10-12 12:30:20 by GabiRoeger)