2) Running A Simple GROMACS Experiment

In this tutorial, you will set up and run a benchmark simulation using GROMACS, a free and open-source application for molecular dynamics.

This tutorial builds off of concepts introduced in previous tutorials. Please make sure you review those before starting with this tutorial’s content, however this tutorial is fully stand-alone as far as steps you need to perform.

Application Information

As mentioned above, this tutorial uses the GROMACS application definition. We will begin with the water_bare and water_gmx50 workloads, as they are able to execute in a short amount of time.

Using a previously installed ramble, the following command can be used to get information about these workloads:

$ ramble info --attrs workloads -v -p "water*" gromacs

Under the workloads marked by Workload: water_bare and Workload: water_gmx50, you should see something like the following output:

Workload: water_gmx50
    Executables: ['pre-process', 'execute-gen']
    Inputs: ['water_gmx50_bare']
    Tags: []
    Variables:
        size:
            Description: Workload size
            Default: 1536
            Suggested Values: ['0000.65', '0000.96', '0001.5', '0003', '0006', '0012', '0024', '0048', '0096', '0192', '0384', '0768', '1536', '3072']
        type:
            Description: Workload type.
            Default: pme
            Suggested Values: ['pme', 'rf']
        input_path:
            Description: Input path for water GMX50
            Default: {water_gmx50_bare}/{size}
Workload: water_bare
    Executables: ['pre-process', 'execute-gen']
    Inputs: ['water_bare_hbonds']
    Tags: []
    Variables:
        size:
            Description: Workload size
            Default: 1536
            Suggested Values: ['0000.65', '0000.96', '0001.5', '0003', '0006', '0012', '0024', '0048', '0096', '0192', '0384', '0768', '1536', '3072']
        type:
            Description: Workload type.
            Default: pme
            Suggested Values: ['pme', 'rf']
        input_path:
            Description: Input path for water bare hbonds
            Default: {water_bare_hbonds}/{size}

Here we see that both of these workloads have a type variable (with possible values of pme and rf) and a size variable with a variety of available sizes.

To determine a suggested software configuration, you can use:

$ ramble info --attrs software_specs,compilers -v gromacs

With this command, you should see output similar to the following:

##################
# software_specs #
##################
impi2018:
    pkg_spec: intel-mpi@2018.4.274
    compiler_spec: None
    compiler: None
    package_manager: spack*

spack_gromacs:
    pkg_spec: gromacs@2020.5
    compiler_spec: None
    compiler: gcc9
    package_manager: spack*

eessi_gromacs:
    pkg_spec: GROMACS/2024.1-foss-2023b
    compiler_spec: None
    compiler: None
    package_manager: eessi

#############
# compilers #
#############
gcc9:
    pkg_spec: gcc@9.3.0
    compiler_spec: None
    compiler: None
    package_manager: spack*

This output does not represent the only possible configuration that works for this application, it only presents a good starting point. When using Ramble, these can be modified freely and will be explored in a later tutorial.

Configuring experiments

For this tutorial, you are going to focus on creating experiments from the water_bare and water_gmx50 workloads. The default configuration will contain experiments for each value of the type variable, and a single value for the size variable.

You will use a Ramble workspace to manage these experiments.

Create and Activate a Workspace

Before you can configure your GROMACS experiments, you’ll need to set up a workspace. You can call this workspace basic_gromacs.

$ ramble workspace create basic_gromacs

This will create a workspace for you in:

$ $RAMBLE_ROOT/var/ramble/workspaces/basic_gromacs

Now you can activate the workspace and view its default configuration.

$ ramble workspace activate basic_gromacs

Alternatively, the workspace creation and activation can be combined in one command with the activate flag (-a):

$ ramble workspace create basic_gromacs -a

You can use the ramble workspace info command after editing configuration files to see how ramble would use the changes you made.

$ ramble workspace info

Configure the Workspace

Within the workspace directory, ramble creates a directory named configs. This directory contains generated configuration and template files. Each of these files can be edited to configure the workspace, and examples will be provided below.

The available files are:

  • ramble.yaml This file describes all aspects of the workspace. This includes the software stack, the experiments, and all variables.

  • execute_experiment.tpl This file is a template shell script that will be rendered to execute each of the experiments that ramble generates.

You can edit these files directly or with the command ramble workspace edit.

To begin, you should edit the ramble.yaml file to set up the configuration for your experiments. For this tutorial, replace the default yaml text with the contents of $RAMBLE_ROOT/examples/basic_gromacs_config.yaml:

NOTE: This workspace utilizes the spack package manager. As a result, it requires spack is installed and available in your path. Modifications to the package_manager variant will change this behavior.

# Copyright 2022-2025 The Ramble Authors
# 
# Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
# https://www.apache.org/licenses/LICENSE-2.0> or the MIT license
# <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your
# option. This file may not be copied, modified, or distributed
# except according to those terms.

ramble:
  variants:
    package_manager: spack
  env_vars:
    set:
      OMP_NUM_THREADS: '{n_threads}'
  variables:
    processes_per_node: 16
    mpi_command: mpirun -n {n_ranks} -ppn {processes_per_node}
    batch_submit: '{execute_experiment}'
  applications:
    gromacs: # Application name
      workloads:
        water_gmx50: # Workload name from application
          experiments:
            pme_single_rank: # Arbitrary experiment name
              variables:
                n_ranks: 1
                n_threads: 1
                size: '0003'
                type: pme
            rf_single_rank:
              variables:
                n_ranks: 1
                n_threads: 1
                size: '0003'
                type: rf
        water_bare:
          experiments:
            pme_single_rank:
              variables:
                n_ranks: 1
                n_threads: 1
                size: '0003'
                type: pme
            rf_single_rank:
              variables:
                n_ranks: 1
                n_threads: 1
                size: '0003'
                type: rf
  software:
    packages:
      gcc9:
        pkg_spec: gcc@9.4.0 target=x86_64
        compiler_spec: gcc@9.4.0
      impi2021:
        pkg_spec: intel-oneapi-mpi@2021.11.0 target=x86_64
        compiler: gcc9
      gromacs:
        pkg_spec: gromacs@2021.6
        compiler: gcc9
    environments:
      gromacs:
        packages:
        - gromacs
        - impi2021

Note that specifying compilers that Spack doesn’t have installed may take a while. To see available compilers, use spack compilers or see Spack’s documentation for more information.

The second file you should edit is the execute_experiment.tpl template file. This file contains a template script that will be rendered into an execution script for each generated experiment. You can feel free to edit it as you need to for your given system, but for this tutorial the default value will work.

Setting Up the Experiments

Now that the workspace is configured correctly, you can set up the experiments in the active workspace using:

$ ramble workspace setup

This command will create experiment directories, download and expand input files, and install the required software stack (and generate spack environments for each workload).

It can take a bit to run depending on if you need to build new software and how long the input files take to download. If you’d like to see what will be installed, you can do a dry run of the setup using:

$ ramble workspace setup --dry-run

For each setup run, a set of logs will be created at:

$ $RAMBLE_ROOT/var/ramble/workspaces/$workspace_root/logs

Each run will have its own primary log, along with a folder containing a log for each experiment that is being configured. While setup is running, you can monitor the process by looking at the contents of:

$ $RAMBLE_ROOT/var/ramble/workspaces/basic_gromacs/logs/setup.latest/gromacs.water_gmx50.pme_single_rank.out

Executing Experiments

After the workspace is set up, its experiments can be executed. The two methods to run the experiments are:

 $ ramble on
or;
 $ ./all_experiments

Analyzing Experiments

Once the experiments within a workspace are complete, the experiments can be analyzed. This is done through:

$ ramble workspace analyze

This creates a results file in the root of the workspace that contains extracted figures of merit. If the experiments were successful, this file will show the following results:

  • Core Time: CPU time (in seconds) spent on the benchmark calculations

  • Wall Time: Elapsed real time (in seconds) spent on the benchmark calculations

  • Percent Core Time: Core Time / Wall Time

  • Nanosecs per day: Nanoseconds of simulation per day at the speed achieved

  • Hours per nanosec: Hours required to calculate 1 nanosecond of simulation at the speed achieved

Workspace Directory Structure

After analyzing the workspace, you can exmine the structure of the workspace at:

$ $RAMBLE_ROOT/var/ramble/workspaces/basic_gromacs

Within this directory, you should see the following directories:

  • configs - Contains all of the configuration files for the workspace

  • experiments - Contains all of the experiment execution directories

  • inputs - Contains all of the input files needed for the experiments

  • logs - Contains all log files from any Ramble command that acts on the workspace

  • shared - Contains auxiliary files the experiment might need, such as environment variable information for licenses

  • software - Contains software environments for the experiments

Cleanup the Workspace

Once you are finished with the tutorial content, ensure you have deactivated the workspace using:

$ ramble workspace deactivate

Additionally, you can remove the workspace using:

$ ramble workspace remove basic_gromacs