Getting Started
User Documentation

The first step is to install the WRENCH library, following the instructions on the installation page.

Running a First Example

Typing make in the top-level directory will compile the examples, and make install will put the examples binaries in the /usr/local/bin folder (for MacOS and most Linux distributions).

WRENCH provides a simple example in the examples/simple-example directory, which generates two executables: a cloud-based example wrench-simple-example-cloud, and a batch-system-based (e.g., SLURM) example wrench-simple-example-batch. To run the examples, simply use one of the following commands:

# Runs the cloud-based implementation
wrench-simple-example-cloud \
<PATH-TO-WRENCH-FOLDER>/examples/simple-example/platform_files/cloud_hosts.xml \
# Runs the batch-based implementation
wrench-simple-example-batch \
<PATH-TO-WRENCH-FOLDER>/examples/simple-example/platform_files/batch_hosts.xml \

Understanding the Simple Example

Both versions of the example (cloud of batch) require two command-line arguments: (1) a SimGrid virtual platform description file; and (2) a WRENCH workflow file.

  • SimGrid simulated platform description file: A SimGrid simulation must be provided with the description of the platform on which an application execution is to be simulated. This is done via a platform description file, in XML, 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 workflow description file formats. Refer to their respective Web sites for detailed documentation.

The source file for the cloud-based simulator is at examples/simple-example/SimulatorCloud.cpp and at examples/simple-example/SimulatorBatch.cpp for the batch-based example. These source files, which are heavily commented, and perform the following:

  • The first step is to read and parse the workflow and the platform files, and to create a simulation object (wrench::Simulation).
  • A storage service (wrench::SimpleStorageService) is created and deployed on a host.
  • A cloud (wrench::CloudComputeService) or a batch (wrench::BatchComputeService) service is created and deployed on a host. Both services are seen by the simulation as compute services (wrench::ComputeService) – jobs can then be submitted to these services.
  • A Workflow Management System (wrench::WMS) is instantiated (in this case the SimpleWMS) with a reference to a workflow object (wrench::Workflow) and a scheduler (wrench::Scheduler). The scheduler implements the decision-making algorithms inside the WMS. These algorithms are modularized (so that the same WMS implementation can be iniated with various decision-making algorithms in different simulations). The source codes for the schedulers, which is of interest to "Developers" (i.e., those users who use the WRENCH Developer API), is in directory examples/scheduler.
  • 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, executes, and completes.
  • Timestamps can be retrieved to analyze the simulated execution.

This simple example can be used as a blueprint for starting a large WRENCH-based simulation project. The next section provides further details about this process.

WRENCH Initialization Tool

The wrench-init tool is a project generator built with WRENCH, which creates a simple project structure with example class files, as follows:

├── CMakeLists.txt
├── src/
│ ├── SimpleSimulator.cpp
│ ├── SimpleStandardJobScheduler.cpp
│ ├── SimpleStandardJobScheduler.h
│ ├── SimpleWMS.cpp
│ └── SimpleWMS.h
├── test/
├── doc/
├── build/
└── data/
├── platform-files/
└── workflow-files/

The SimpleSimulator.cpp source file contains the class representing the simulator (either cloud or batch). SimpleStandardJobScheduler.h and SimpleStandardJobScheduler.cpp contain a simple implementation for a wrench::StandardJobScheduler; SimpleWMS.h and SimpleWMS.cpp denote the implementation of a simple workflow management system. Example platform and workflow files are also generated into the data folder. These files provide the minimum necessary implementation for a WRENCH-enabled simulator.

The wrench-init tool only requires a single argument, the name of the folder where the project skeleton will be generated:

$ wrench-init <PROJECT_FOLDER>

Additional options supported by the tool can be found by using the wrench-init --help command.

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