Getting Started
Internal 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

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.

In addition to the common installation steps, WRENCH's internal developers are strongly encouraged to install the following dependencies/tools:

  • Google Test - version 1.8 or higher (for running test cases)
  • Doxygen - version 1.8 or higher (for generating documentation)

WRENCH Directory and File Structure

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

.
+-- doc # 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
+-- sonar-project.properties # Configuration file for Sonar Cloud Continuous Code Quality
+-- LICENSE.md # WRENCH license disclaimer
+-- README.md