Getting Started
Internal 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 worfklow 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::CloudService) or a batch (wrench::BatchService) 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, and 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.

Preparing the Environment

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

Internal developers are expected to contribute code to WRENCH's core components. Please, refer to the API Reference to find the detailed documentation for WRENCH functions.

Note: It is strongly recommended that WRENCH internal developers (contributors) fork WRENCH's code from the GitHub repository, and create pull requests with their proposed modifications.

WRENCH Directory and File Structure

WRENCH follows a standard C++ project directory and files structure:

+-- doc # Documentation source files
+-- docs # Generated documentation files
+-- examples # Examples folder (includes workflows, platform files, and implementations)
+-- include # WRENCH header files - .h files
+-- src # WRENCH source files - .cpp files
+-- test # WRENCH test files
+-- tools # Tools for supporting documentation generation and release builds
+-- .travis.yml # Configuration file for Travis Continuous Integration
+-- # Configuration file for Sonar Cloud Continuous Code Quality
+-- # WRENCH license disclaimer