5) Changing A Software Stack

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
$ ramble workspace info

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

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/vector_matrix_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:
        '{app_workloads}': # Workload name from application
          experiments:
            '{type}_{n_ranks}ranks': # Arbitrary experiment name
              variables:
                app_workloads: [water_gmx50, water_bare]
                n_ranks: [1, 2]
                n_threads: 1
                size: '0003'
                type: [pme, rf]
              matrix:
              - app_workloads
              - type
              - n_ranks
  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 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.

Software Description

Now that your workspace has been created, and configured with the default workspace configuration file you can examine the workspace contents. You can execute the following command to see what software environments and packages 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 regarding software packages and environments:

Software Stack:
  Packages:
    gcc9:
      Rendered Packages:
        gcc9:
          Spec: gcc@9.4.0 target=x86_64
          Compiler spec: gcc@9.4.0
    impi2021:
      Rendered Packages:
        impi2021:
          Spec: intel-oneapi-mpi@2021.11.0 target=x86_64
          Compiler: gcc9
    gromacs:
      Rendered Packages:
        gromacs:
          Spec: gromacs@2021.6
          Compiler: gcc9
  Environments:
    gromacs:
      Rendered Environments:
        gromacs Packages:
          - gromacs
          - impi2021

Currently, this command outputs every package and software environment definition, even if they are not used directly by an experiment. By default, each experiment expects a software environment that is named the same as the application. For example, an experiment for the application gromacs expects a software environment named gromacs. This can be overridden using the variable env_name, which can be the name of any environment defined in the workspace configuration file.

The relevant portion of the workspace configuration file is:

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

In this configuration, the packages block defines software packages that can be used to build experiment environments out of. The environments block defines software environments which can be used for the experiments listed within the ramble:applications block. Keys within both packages and environments are the name of the package or environment (respectively). Each environment has a packages block, which contains a list of package names that are defined in the higher level packages block.

These are further documented in the Software configuration section documentation.

Changing Software Definitions

In this workspace, we have variants:package_manager:spack which injects the use of the spack package manager. You are able to change the package manager through this variant option, however the remainder of this tutorial will assume the package manager is spack. When changing the software definitions in a workspace, many options are available to you. For example, you could modify the compiler used for building GROMACS (as defined on line 45), or you could modify the MPI used for these experiments (as seen on line 53). However, we will explore changing aspects of GROMACS itself (such as its version or variants).

NOTE: It is important to note that changing aspects of compilation could result in build-time errors that need to be resolved before Ramble can generate experiments. Oftentimes it is both easier and faster to work through these issues (if you encounter them) outside of Ramble, using the package manager directly. Because Ramble uses the package manager, if the package is already installed it will not cause the package manager to re-install it.

In order to get information about what changes you can make to the GROMACS package, you can use:

$ spack info gromacs

This command will output all of the supported versions of GROMACS, along with the variants for GROMACS which can modify its behavior. While you can change any of these, we’ll begin by only modifying the version of GROMACS from 2021.6 to 2021.7.

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.

Once the ramble.yaml file is opened, change the version 2021.6 to 2021.7 on line 47. Then save and exit the files. These changes should now be reflected in the output of:

$ ramble workspace info

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

NOTE: Since you changed the package definition for GROMACS, it will be recompiled (unless you compiled it outside of Ramble) during the ramble workspace setup command. This will likely take longer than changing experiments and performing setup again.

Adding Package Variants

So far, we have only explored changing the version a package used. More complicated changes to the package specs can be made by adding variant definitions. This can be directly added to the pkg_spec lines within the package definitions in a workspace’s ramble.yaml.

The pkg_spec attribute can be parameterized with variable definitions also, to allow a wide range of variants to be explored with a single configuration.

Vector and Matrix Software Definitions

Package and environment definitions support the same vector and matrix logic as introduced in 4) Using Vectors and Matrices. Package and environment names should similarly be unique, and can use placeholder values for variable definitions.

As an example, to explore both of the versions of GROMACS described in this tutorial, your ramble.yaml could look like the following:

# 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}'
    gromacs_version: [2021.6, 2021.7]
  applications:
    gromacs: # Application name
      workloads:
        '{app_workloads}': # Workload name from application
          experiments:
            '{type}_{n_ranks}ranks-{gromacs_version}': # Arbitrary experiment name
              variables:
                app_workloads: [water_gmx50, water_bare]
                n_ranks: [1, 2]
                n_threads: 1
                size: '0003'
                type: [pme, rf]
                env_name: gromacs-{gromacs_version}
              matrix:
              - app_workloads
              - type
              - n_ranks
              - gromacs_version
  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-{gromacs_version}:
        pkg_spec: gromacs@{gromacs_version}
        compiler: gcc9
    environments:
      gromacs-{gromacs_version}:
        packages:
        - gromacs-{gromacs_version}
        - impi2021

Using this configuration file, you can examine what changes it would make to your workspace through:

$ ramble workspace info
or;
$ ramble workspace setup --dry-run

Changing Package Managers

The experiments in this tutorial assumed the use of spack as your package manager. Ramble provides an option to change the package manager used in experiments. The workspace used contains the following lines:

variants:
  package_manager: spack

This tells Ramble which package manager object to use when constructing the experiments. The available package managers can be viewed using:

$ ramble list --type package_managers

In addition to any of these package managers, experiments can set variants:package_manager to either None or null to disable package managers for the experiment.

Cleaning the Workspace

Once your are finished with the tutorial content, deactivate your workspace using:

$ ramble workspace deactivate

Additionally, you can remove the entire workspace and all of its contents using:

$ ramble workspace remove basic_gromacs