3) Modifying A GROMACS Experiment
In this tutorial, you will learn how to modify an existing workspace configuration that contains experiments 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.
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.yamlThis file describes all aspects of the workspace. This includes the software stack, the experiments, and all variables.
execute_experiment.tplThis 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.
Experiment Descriptions
Now that your workspace has been configured, and activated, You can execute the following command to see what experiments the workspace currently contains:
$ ramble workspace info
This command provides a summary view of the workspace. It includes the experiment names, and the software environments. As an example, its output might contain the following information:
Experiments:
Application: gromacs
Workload: water_gmx50
Experiment: gromacs.water_gmx50.pme_single_rank
Application: gromacs
Workload: water_gmx50
Experiment: gromacs.water_gmx50.rf_single_rank
Application: gromacs
Workload: water_bare
Experiment: gromacs.water_bare.pme_single_rank
Application: gromacs
Workload: water_bare
Experiment: gromacs.water_bare.rf_single_rank
To get detailed information about where variable definitions come from, you can use:
$ ramble workspace info --expansions
The experiments section of this command’s output might contain the following:
Experiments:
Application: gromacs
Workload: water_gmx50
Experiment: gromacs.water_gmx50.pme_single_rank
Variables from Workspace:
processes_per_node = 16 ==> 16
mpi_command = mpirun -n {n_ranks} -ppn {processes_per_node} ==> mpirun -n 1 -ppn 16
batch_submit = {execute_experiment} ==> {execute_experiment}
Variables from Experiment:
n_ranks = 1 ==> 1
n_threads = 1 ==> 1
size = 0003 ==> 0003
type = pme ==> pme
Application: gromacs
Workload: water_gmx50
Experiment: gromacs.water_gmx50.rf_single_rank
Variables from Workspace:
processes_per_node = 16 ==> 16
mpi_command = mpirun -n {n_ranks} -ppn {processes_per_node} ==> mpirun -n 1 -ppn 16
batch_submit = {execute_experiment} ==> {execute_experiment}
Variables from Experiment:
n_ranks = 1 ==> 1
n_threads = 1 ==> 1
size = 0003 ==> 0003
type = rf ==> rf
Application: gromacs
Workload: water_bare
Experiment: gromacs.water_bare.pme_single_rank
Variables from Workspace:
processes_per_node = 16 ==> 16
mpi_command = mpirun -n {n_ranks} -ppn {processes_per_node} ==> mpirun -n 1 -ppn 16
batch_submit = {execute_experiment} ==> {execute_experiment}
Variables from Experiment:
n_ranks = 1 ==> 1
n_threads = 1 ==> 1
size = 0003 ==> 0003
type = pme ==> pme
Application: gromacs
Workload: water_bare
Experiment: gromacs.water_bare.rf_single_rank
Variables from Workspace:
processes_per_node = 16 ==> 16
mpi_command = mpirun -n {n_ranks} -ppn {processes_per_node} ==> mpirun -n 1 -ppn 16
batch_submit = {execute_experiment} ==> {execute_experiment}
Variables from Experiment:
n_ranks = 1 ==> 1
n_threads = 1 ==> 1
size = 0003 ==> 0003
type = rf ==> rf
The variables mpi_command, processes_per_node, and batch_submit
come from the workspace scope towards the top of the YAML file. Each experiment
has its own definition for n_ranks, n_threads, size, and type.
The experiments in this configuration use both the water_bare and
water_gmx50 workloads.
Using Workload Variables
Application definitions are allowed to expose variables that can be used within experiments. These are called workload variables. User can view the available variables with the following command:
$ ramble info --attrs workloads -v -p "water*" gromacs
Which should contain the following information:
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}
Within each of the workloads your workspace has experiments for, you can see
definitions for both size and type. The Suggested Values attribute
defines possible values for each of the variables, which can be defined within
your workspace’s ramble.yaml file.
While these variables contain Suggested Values some other variable
definitions can take any value you want. As a result, they might not provide
anything other than a default value. While the default value is expected to
function properly, you are allowed to override their definition within the
ramble.yaml if your experiments would benefit from it. However, be aware
that this also has the potential to change the behavior of your experiments and
is considered an advanced action.
Editing Experiments
Now that you know how to determine which values are possible, select one or
more of the possible values for the size variable. You will modify the
experiments in your workspace to use this (remember, you have 4 experiments
defined currently).
NOTE The larger the value, the more expensive the experiment will be. However you can give each experiment a unique value.
To make editing the workspace easier, use the following command (assuming you
have an EDITOR environment variable set):
$ ramble workspace edit
This command opens the ramble.yaml file, along with any *.tpl files in
the workspace’s configs directory. The root directory of the workspace can
be seen in the Location attribute output from:
When the ramble.yaml is open, modify any of the experiment’s size
variable definitions that you want to. Finally, save and exit the file.
These changes should now be reflected in the output of:
$ ramble workspace info --expansions
Execute Experiments
Now that you have made the appropriate modifications, set up, execute, and analyze the new experiments using:
$ ramble workspace setup
$ ramble on
$ 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
If you have a results file from the previous tutorial,
you can compare it with the newly created results file to see what impact
changing the size variable had on your figures of merit.
Cleaning the Workspace
After you are finished with the content of this tutorial, make sure you deactivate your workspace using:
$ ramble workspace deactivate
If you no longer need the workspace materials, remove the entire workspace with:
$ ramble workspace remove basic_gromacs