Getting Started
User Documentation

The first step is to have WRENCH library installed. If it is not done yet, please follow the instructions to install it.

Running a First Example

The WRENCH distribution provides an example WMS implementation (SimpleWMS) available in the examples folder. Note that a simple installation via make && make install compiles all examples.

WRENCH provides two implementations for the SimpleWMS example: a cloud-based implementation wrench-simple-wms-cloud, and an implementation to run workflows in a batch system (e.g., SLURM) wrench-simple-wms-batch.

By default, a successful WRENCH installation puts the examples binaries in the /usr/local/bin folder (for MacOS and most Linux distributions). To run the examples, simply use one of the following commands:

# running the cloud-based implementation
wrench-simple-wms-cloud <PATH-TO-WRENCH-SRC-FOLDER>/examples/cloud_hosts.xml <PATH-TO-WRENCH-SRC-FOLDER>/examples/genome.dax
# running the batch-based implementation
wrench-simple-wms-batch <PATH-TO-WRENCH-SRC-FOLDER>/examples/batch_hosts.xml <PATH-TO-WRENCH-SRC-FOLDER>/examples/genome.dax

Understanding the Simple-WMS Examples

The SimpleWMS example requires two arguments: (1) a SimGrid virtual platform description file; and (2) a WRENCH workflow file.

SimGrid virtual platform description file: Any SimGrid simulation must be provided with the description of the platform on which an application exeuction is to be simulates. This is done via a platform desctription file that includes definitions of compute hosts, clusters of hosts, storage resources, network links, routes between hosts, etc. A detailed description on how to create a platform description file can be found here.

WRENCH workflow file: WRENCH provides native parsers for DAX (DAG in XML) and JSON worfklow description file formats. Refer to their respective Web sites for detailed documentation.

The SimpleWMS example implementations (either cloud or batch) are structured as follows:

  • The first step is to read and parse the workflow and the SimGrid platform files, and create a simulation object (wrench::Simulation).
  • A storage service (wrench::SimpleStorageService) is created and deployed on a host.
  • A cloud (wrench::CloudService) or a batch (wrench::BatchService) service is created and deployed on a host. Both services are seen by the simulation engine as a compute service (wrench::ComputeService) – jobs can then be scheduled to these resources.
  • A WMS (wrench::WMS) is instantiated (in this case the SimpleWMS) with a reference to the workflow object (wrench::Workflow) and a scheduler (wrench::Scheduler). For the cloud example, a cloud scheduler is required to decide when to spawn VMs on hosts. The batch service does not require a specific scheduler, since resources are fixed. In such cases, a regular scheduler can be used.
  • A file registry (wrench::FileRegistryService), a.k.a. a file replica catalog, which keeps track of files stored in different storage services, is deployed on a host.
  • Workflow input files are staged on the storage service
  • The simulation is launched.
  • Timestamps can be retrieved to inspect the simulation result.

Preparing the Environment

Importing WRENCH

For ease of use, all WRENCH abstractions are accessed via a single include statement:

#include <wrench.h>

Creating Your CMakeLists.txt File

Below is an example of a CMakeLists.txt file that can be used as a starting template for developing a WRENCH application compiled using cmake:

cmake_minimum_required(VERSION 3.2)
add_definitions("-Wall -Wno-unused-variable -Wno-unused-private-field")
# include directories for dependencies and WRENCH libraries
include_directories(src/ /usr/local/include /usr/local/include/wrench)
# source files
# test files
# wrench library and dependencies
find_library(WRENCH_LIBRARY NAMES wrench)
find_library(SIMGRID_LIBRARY NAMES simgrid)
find_library(PUGIXML_LIBRARY NAMES pugixml)
find_library(LEMON_LIBRARY NAMES emon)
find_library(GTEST_LIBRARY NAMES gtest)
# generating the executable
add_executable(my-executable ${SOURCE_FILES})
install(TARGETS my-executable DESTINATION bin)
# generating unit tests
add_executable(unit_tests EXCLUDE_FROM_ALL
${GTEST_LIBRARY} wrench -lpthread -lm