FabMD Workflow

Introduction

FabMD is a tool that allows for the easy execution of molecular dynamics simulations in remote machines. This section of the documentation will cover an example of how one would go about configuring FabMD and running a simulation using LAMMPS.

Example of workflow for FabMD

First, it is important to define a simulation. We create a directory called my-simulation which contains a single LAMMPS input script called in.lammps that defines the entire simulation. We need to make FabMD aware of this directory, which we can do by placing the my-simulation directory inside of the config_files directory (FabSim3/plugins/FabMD/config_files). With this, FabMD now recognises the LAMMPS simulation and we are free to call any of the fabsim commands on the command line.

Before submitting the simulation to a remote machine, two YAML files must be edited. First we modify the file FabSim3/deploy/machines_user.yml and add our login credentials in the template so that FabMD knows where to run the simulation. In this example we will use the PSNC HPC system called Eagle, so the only parameter we need to add is the username we use for that computer. Other computers may have have more parameters that need to be added, such as for example, the UK National Supercomputer ARCHER2, which also requires a password to be entered.

The next file that needs to be updated is FabSim3/plugins/FabMD/machines_FabMD_user.yml. In this file you can set the path to the LAMMPS executable on the remote machine. However, most HPC clusters have LAMMPS available as a module and this can be added in the loaded modules section of the file. This means that the lammps_exec parameter can be set to the LAMMPS command rather than the path of the compiled executable. For example, an arbitrary remote machine might look like:

remote-machine-name:
   lammps_exec: "lmp"
   ...
   ...
   ...
   modules:
      loaded: ["lammps/15Apr2020"]

After all this configuration, we can submit a simulation to a remote machine using the command:

fabsim eagle lammps:my-simulation

To recap, this command can be read as follows: execute LAMMPS on a simulation in the directory my-simulation inside the remote machine eagle. This command will automatically generate a batch script which is sent to the scheduler so that the remote machine can run the simulation. By default, the lammps subcommand will execute the file called in.lammps. This behaviour can be changed by adding the optional command:

fabsim eagle lammps:my-simulation,lammps_input=new-input.in

Where new-input.in is the name of the LAMMPS script you wish to execute.

Additionally, other parameters can be changed such as the number of cores that are used or the maximum job_wall_time. An example of a optionally configured command is:

fabsim eagle lammps:my-simulation,cores=1,job_wall_time=0:10:0

Once the simulation has been submitted, we can check on the status of the job using the command:

fabsim eagle stat

The information provided will differ between machines, but in general this command will give the runtime of the simulation and which nodes are being used.

When the job has completed, we can use the command:

fabsim eagle fetch_results

To copy all of the results from the remote machine to our local computer.

To summarise, a typical workflow would be composed of the three commands:

fabsim <remote machine name> lammps:<directory in config_files>
fabsim <remote machine name> stat
fabsim <remote machine name> fetch_results