genericMD CLI

Sometimes, you may want to track commands outside of GROMACS. The genericMD CLI allows you to keep track of these commands directly from the aiida-gromacs plugin installation.

GROMACS specific vs genericMD CLI process submissions

First let’s take a look at what a process submitted using a gromacs specific CLI command compares with submitting the job with the genericMD CLI:

Submitting a pdb2gmx process using gmx_pdb2gmx:

gmx_pdb2gmx -f 1AKI_clean.pdb -ff oplsaa -water spce -o 1AKI_forcefield.gro -p 1AKI_topology.top -i 1AKI_restraints.itp

Submitting the equivalent process with genericMD

genericMD --code gmx@localhost \
--command "pdb2gmx -i 1AKI_restraints.itp -o 1AKI_forcefield.gro -p 1AKI_topology.top -ff oplsaa -water spce -f 1AKI_clean.pdb" \
--inputs path/to/1AKI_clean.pdb \
--outputs 1AKI_restraints.itp --outputs 1AKI_topology.top --outputs 1AKI_forcefield.gro

As you can see, using the genericMD CLI is more verbose, but it does allow for submitting any command you want to keep track of with AiiDA.

Note

The quoted command text for the --command flag does not need to include the path to the input files, instead you include the paths to files in the --inputs flag.

Note

By default, the outputs produced from the command are saved in a output_dir in the current working directory. To change where the output files are saved, set the path with the --output_dir flag.

How to submit a process with genericMD

To submit an AiiDA process for tracking input and output files of a generic command, there are several things you need to know beforehand:

  1. what the full command you want to run is,

  2. where is the program you’re using in your command installed,

  3. what are the input file names you’re using in the command,

  4. and what are the output file names outputted from your command.

Once you know this information, you can build a genericMD process submission. Let’s take a look at the example below for a submission for tracking the inputs and outputs of a diff command:

genericMD --code bash@localhost --command "diff file1.txt file2.txt > out.txt" --inputs file1.txt --inputs file2.txt --outputs out.txt

Here,

  1. the command we want to run is diff file1.txt file2.txt > out.txt, which is specified with the --command flag and wrapped in quotation marks

  2. the diff utility is installed on the local computer and can be run via bash, this is communicated to AiiDA with --code bash@localhost

  3. each input file used in the diff command needs to be explicitly defined using the --inputs flag, this allows for AiiDA to keep track of these files

  4. similarly for the output files, use the --outputs flag to define each output from the command, which allows AiiDA to track these files

A few things to consider when using genericMD, firstly the inputs and ouputs of a command need to be known before submitting the process.

Warning

Any inputs/outputs not included in the genericMD submission with --inputs and --outputs flags repectively, will not be included as a node in the provenance graph!!

Another example to submit a process with genericMD

The example above for tracking the diff command may be useful for tracking changes to files made on non-command line based programs, for example when using a GUI to add or delete atoms in a .pdb file. Here’s another example for tracking a command outside of GROMACS using Packmol to create the initial system geometry for MD simulations.

First, we add the packmol code:

verdi code create core.code.installed --label packmol --computer localhost --filepath-executable ~/packmol-20.14.2/packmol
    Report: enter ? for help.
    Report: enter ! to ignore the default and set no value.
    Description: Initial configurations for Molecular Dynamics Simulations by packing optimization
    Default `CalcJob` plugin: genericMD
    Escape using double quotes [y/N]: y
    Success: Created InstalledCode<3>

This assumes that Packmol is already installed on your computer in the path ~/packmol-20.14.2/packmol, if not then follow the Packmol installation guide or follow the summarised guide below.

  1. Download the packmol-20.13.0.tar.gz file

  2. Expand the files with tar -xvzf packmol-20.13.0.tar.gz

  3. Build the executable with cd packmol; make

You can check the Packmol code is added with:

verdi code list
    Full label           Pk  Entry point
    -----------------  ----  -------------------
    gmx@localhost         1  core.code
    bash@localhost        2  core.code
    packmol@localhost     3  core.code.installed

Once the Packmol is added as a code, we can track a Packmol code with the genericMD calculation with:

genericMD --code packmol@localhost --command "< packmol.inp" \
--inputs path/to/packmol.inp --inputs path/to/input.pdb \
--outputs path/to/output.pdb

That’s it, you can track a command from code installed on your computer external to GROMACS.