Getting Started {#getting-started}


User Documentation
@endWRENCHDoc @WRENCHDeveloperDoc
Developer Documentation
@endWRENCHDoc @WRENCHInternalDoc
Internal Documentation

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

Running a First Example # {#getting-started-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 {#getting-started-example-simple}

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.

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:

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 # {#getting-started-wrench-init}

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. @endWRENCHDoc

Preparing the Environment # {#getting-started-prep}


Importing WRENCH ## {#getting-started-prep-import}

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


#include <wrench.h>



#include <wrench-dev.h>

Note that wrench-dev.h is the only necessary include statement to use WRENCH. It includes all interfaces and services provided in wrench.h (user API), as well as additional interfaces to develop your own algorithms and services.


Creating Your CMakeLists.txt File ## {#getting-started-prep-cmakelists}

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 # {#getting-started-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