FMAP: A Platform for the Development of Distributed Multi-Agent Planning Systems
User Manual (ver. 1.0)
FMAP is a cross-platform Java-based software designed to streamline the development of Multi-Agent Planning (MAP) applications where several agents with planning capabilities must coordinate with each other in order to jointly synthesize a solution plan that solves a set of goals.
The FMAP platform makes extensive use of Java interfaces, which encapsulate the different components of the code, enabling for an easy replacement of the existing algorithms. This feature greatly simplifies the arduous task of developing and integrating new distributed planning algorithms and heuristic functions. FMAP includes a thoroughly-tested communication infrastructure based on the standard FIPA messaging protocols.
FMAP focuses on distributed heuristic search. Each planning agent in the platform features an embedded search engine based on forward-chaining partial-order planning. In order to solve a MAP task, the FMAP platform performs three stages:
Parsing: agents lexically and syntactically analyze their domain and problem files, thus obtaining a set of data structures that store the MAP task.
Grounding: this stage involves instantiating the variables of the planning actions, state variables and values of the agents' parsed tasks. During this stage, agents jointly build a distributed relaxed planning graph (disRPG) in order to generate only those grounded actions that are applicable at planning time.
Planning: after pre-processing the MAP task, agents carry out the planning procedure, which comprises the following steps:
- Agents select an open node of the search tree for expansion according to some heuristic estimate.
- Agents individually expand the selected node using their embedded search engines.
- Once the successors are generated, agents remove the private information from the plans before communicating the node information to the others. Therefore, each agent in FMAP keeps a privacy-preserving copy of the joint search tree.
Along with the present user manual, the FMAP repository includes the complete javadoc documentation of the source code, accessible through the /javadoc/index.html file. Moreover, a comprehensive collection of MAP domains encoded with the FMAP language is included in the /Domains/ directory of the repository. FMAP is also compatible with the factored benchmarks of the 2015 CoDMAP competition.
Setting up FMAP
The FMAP.jar file, located in the root folder of the FMAP repository, allows the user to easily set up and run the platform.
FMAP includes two different modes of operation; namely, the command-line and interactive modes. The platform is launched via the following command:
java -jar FMAP.jar [[agent-name agent-domain.pddl agent-problem.pddl]+ agent-list.txt]?
FMAP command-line mode
In order to run the command-line mode of the platform, several parameters must be provided. For each agent, the user must enter the following information:
- agent-name: name of the agent, as described in the objects section of the agent's problem file.
- agent-domain.pddl: domain file of the agent.
- agent-problem.pddl: problem file of the agent.
Additionally, an agent-list.txt file must be provided. This file lists the names and IP addresses of the participants:
agent1 ip - address - agent1
agent2 ip - address - agent2
For example, in order to run the driverlog pfile4 included in the /Domains/ folder of the FMAP distribution on a single machine, the following command must be introduced:
java -jar FMAP.jar driver1 /Domains/driverlog/Pfile4/DomainDriverlog.pddl /Domains/driverlog/Pfile4/ProblemDriverlogdriver1.pddl driver2 /Domains/driverlog/Pfile4/DomainDriverlog.pddl /Domains/driverlog/Pfile4/ProblemDriverlogdriver2.pddl driver3 /Domains/driverlog/Pfile4/DomainDriverlog.pddl /Domains/driverlog/Pfile4/ProblemDriverlogdriver3.pddl agent-list.txt
The agent-list.txt file must be encoded as follows:
The command-line mode of FMAP allows to execute a MAP task in multiple hosts, running several agents in each host. In order to launch the driverlog pfile4 in two different machines with associated IP addresses 100.100.100.1 and 100.100.100.2 (assuming that agents driver2 and driver3 are allocated on host 100.100.100.2), the following commands must be introduced:
- Host 1: java -jar FMAP.jar driver1 /Domains/driverlog/Pfile4/DomainDriverlog.pddl /Domains/driverlog/Pfile4/ProblemDriverlogdriver1.pddl agent-list.txt
- Host 2: java -jar FMAP.jar driver2 /Domains/driverlog/Pfile4/DomainDriverlog.pddl /Domains/driverlog/Pfile4/ProblemDriverlogdriver2.pddl driver3 /Domains/driverlog/Pfile4/DomainDriverlog.pddl /Domains/driverlog/Pfile4/ProblemDriverlogdriver3.pddl agent-list.txt
The agent-list file must include the IP addresses of each agent's host:
In this mode, the solution plan is returned in the format of the of the 2015 CoDMAP distributed track, which is compatible with the VAL plan validator.
FMAP interactive mode
Executing the FMAP platform without providing optional parameters (java -jar FMAP.jar) launches the interactive mode of FMAP. In this mode, agents are launched on a single host only.
In order to interactively execute the driverlog pfile2 task, the user must introduce the basic information:
- These fields allow to enter the basic information of each agent in the MAP task; namely, the Agent's name, Domain file and Problem file.
- Once the agent's information is provided, the agent must be registered via the Add agent button. The Clear agents button clears the current selection.
- The agents of the MAP task can be saved to a file through the Save agents button. This file allows to load all the agents of the task at once via the Load agents button.
- The search scheme applied by the agents to solve the MAP task is selected through the Heuristic function list. The default option, DTG + Landmarks, launches the multi-heuristic search scheme of the MH-FMAP solver, which combines the h_DTG and h_Land heuristics (see related publications below). The current version of the platform also supports DTG, the search strategy of FMAP, which uses the h_DTG heuristic function to guide the search, and FF, which uses the well-known h_FF heuristic function adapted to a MAP context. The remaining option, Inc. DTG + Landmarks, executes an experimental mode that makes use of h_DTG and h_Land.
- The right-hand checkboxes allow the user to configure additional options: Same objects filtering removes the same objects of the task, and Planning trace activates/deactivates the planning trace printed by the agents in the interactive mode.
- Once the configuration is completed, the Start agents button launches the planning agents and starts the resolution of the MAP task.
For each agent in the MAP task, one Agent menu is displayed, as shown in the above figure. This menu includes several options to visualize the different data structures managed by the agent during the resolution of the task:
- In the Trace menu, the agent prints a log of the planning trace, including the plans it builds at each iteration of the search as well as the plans it receives from other agents. Double-clicking on the name of a plan displays it in the Search tree viewer.
- The disRPG menu displays the distributed relaxed planning graph jointly computed by the planning agents at grounding time. The disRPG alternates levels of actions and fluents. Fluents are labelled with the agents that achieve them.
- The Landmarks viewer displays the landmark graph used by the h_Land heuristic function. White nodes represent snigle landmarks, while grey nodes stand for disjunctive landmarks. The vertices indicate necessary orderings among landmarks.
- The left-hand side of the Search tree viewer showcases the search tree. Nodes with successors are marked with a folder icon. Clicking on the left-hand cornder of one of these nodes displays its direct successors. Clicking on a node shows the associated plan on the right-hand viewer. The graphical representation of a plan can be zoomed in/out via the mouse wheel. Actions can also be dragged and dropped for optimal visualization. Finally, double-clicking an action, ordering or causal link displays the information of such element.
- The Status field indicates the current stage of the resolution process. States include parsing, grounding, planning, idle (which is displayed the task is solved) and error (which is shown in case that an error occurred). The status bar indicates the progress of the search according to the best heuristic value obtained so far. The color of the bar indicates the progress of the search: in case the search is stuck in a plateau, the bar wil progressively get a red tone; otherwise, the progress bar will be visualized in blue.
Javadoc API description
The complete Javadoc description of FMAP's API can be found here.
The following papers describe existing MAP systems developed under the FMAP platform:
Jaume Jordán, Alejandro Torreño, Mathijs de Weerdt, Eva Onaindia. A Better-Response Strategy for Self-Interested Planning Agents. Applied Intelligence, DOI 10.1007/s10489-017-1046-5, (2017)
Alejandro Torreño, Eva Onaindia, Óscar Sapena. Global Heuristics for Distributed Cooperative Multi-Agent Planning. 25th International Conference on Automated Planning and Scheduling (ICAPS'15), pp. 225-233, (2015)
Alejandro Torreño, Eva Onaindia, Óscar Sapena. FMAP: Distributed Cooperative Multi-Agent Planning. Applied Intelligence, Vol. 41(2), pp. 606-626, (2014)
Alejandro Torreño, Eva Onaindia, Óscar Sapena. A Flexible Coupling Approach to Multi-Agent Planning under Incomplete Information. Knowledge and Information Systems, Vol. 38(1), pp. 141-178, (2014)
Alejandro Torreño, Eva Onaindia, Óscar Sapena. FMAP: A Heuristic Approach to Cooperative Multi-Agent Planning. ICAPS'13 DMAP Workshop on Distributed and Multi-Agent Planning, pp. 84-92, (2013)
For technical assistance, please contact the authors of this software at (replace AT by @):
- atorreno AT dsic.upv.es
- osapena AT dsic.upv.es