Home

Bartender Wiki

Bartender is a program that helps with the parametrization of molecules for the Martini 3 coarse-grained forcefield. Given an atomistic molecular structure (in XYZ, PDB or GRO format) and an input file, it will generate bonded parameters for the Martini 3 representation of the given molecule.

Unlike other programs, Bartender does not require you to parametrize an atomistic classical model for your molecule and run an MD trajectory. Instead, Bartender runs a Born-Oppenheimer MD simulation using one of the GFN-xTB methods, which include both classical and quantum-based models. Bartender still allows you to use your own trajectory, if you have one.

The main output of Bartender is a file named gmx_out.itp, containing the bonded parameters requested. Several different functions can be used to model some bonded terms. In those cases, Bartender fits the available functions, and prints them the fits, leaving all but one commented. In the current version, it is up to the user to decide which function is best to use for each case. Bartender, however, provides data to inform those decision.

Installation

Binary installation

This is the easiest and recommended way to install Bartender. As of now, it is only available for Linux.

Simply download the binary, uncompress it in the directory where you want the program installed (say, /home/something/bartender) and follow the instrucctions in the INSTALL file.

Compiling from source

Compiling Bartender from source is not difficult, assuming you have the Go toolchain installed. If you do not require XTC trajectory format support, Bartender does not contain non-Go code (except for a couple of helper Python and shell scripts), so you should be able to compile it with:

go install github.com/Martini-Force-Field-Initiative/Bartender

In addition, you will need to install the xtb program.

If you do require XTC support, things are a bit trickier. You will need to first download and install the xdrlibrary (which includes putting the library and include files locations in the relevant shell variables). Then you need to download the Bartender repository from Github. Then you should be able to complie by doing:

go build -tags "xtc"

Bartender use

For a detailed example of Bartender use see this section

The basic use of Bartender is as follows:

bartender [FLAGS] geometry.xyz bartender.inp

Note that the flags (if used) have to be given before the other two arguments.

geometry.xyz is the molecular structure for the atomistic systems, in the xyz format. PDB and GRO formats are also supported. If a PDB file is used, it needs to be correctly formatted. There are programs that claim to write PDB files, but don't adhere to the standard. Files produced by those programs maight not work with Bartender.

bartender.inp is the Bartender input file.

The Bartender input

The Bartender input file contains the atoms to beads mapping, the virtual site definitions and the different bonded terms for Bartender to parametrize. The format is fairly simple. A sample input file follows:

#Lines starting with "#" are comments. Only "full line" comments are allowed!
#note that you can assign half (or less) of an atom to a bead. 
#Just divide it by the number you want. Note that all the 
#atom and bead numbers are 1-based
BEADS
1 8,9,10,18,19,20,21
2 6/2,11,20
3 6/2,7,17
#you can add comment lines anywhere
4 16,5,22,1,12
5 15,4,3/2,14/2 
6 13,2,3/2,14/2
#The virtual sites section is similar to the 
#BEADS section, except for the last field
#which is the Gromacs function number. The way the 
#virtual site is defined will depend on the function
#number, and the number of atoms. #This section HAS to go 
#after the BEADS section
VSITES
7 1,2,3 1  
#The next sections specify the bonded terms you 
#want parametrized, in terms of the corresponding beads.
BONDS
1,2
1,3
1,4 
4,5
4,6
ANGLES
1,4,5 
1,4,6
1,2,4
2,4,5
5,4,2
4,2,1
DIHEDRALS
1,2,4,5
5,4,2,1
IMPROPERS  
3,2,1,4

When there are many terms to parametrize, be careful not to include beads that are not defined (which causes Bartender to crash) and to define correctly define the terms you want (terms wrongly defined could be obtained by Bartender with no obvious issue, only to produce unstable, or, worse, just wrong simulations).

A word of caution is advised at this point: While Bartender will always produce an itp using the input data, the stability of the model is highly dependent on the mapping the user defines. One example where this is problematic is for large and/or rigid molecules. Due to the rigidity of the molecule, many if not all of the bonds will actually be constraints. Too many constraints within a CG model may lead to crashes due to instability. The solution in this case is to use virtual sites, eliminating many of the problematic/conflicting bonded parameters.

A second issue which requires an alert is the definition of dihedrals passing through angles that can reach either 0 or 180 degrees. This is a known source of model instability and frequent crashes. In cases where one can define the dihedral using other beads whose angles are farther away from these two extremes, this preferred. In cases where there is no other option, two approaches can be followed: 1) checking the dihedral to see if it really is necessary as many dihedrals have such low force constants that for all intents and purposes, they are free rotors and can be ignored and 2) adjusting the angles, even worsening the fit to reference data, by pushing them away from 0/180 deg, increasing their force constant and setting the angle type to 10. By definition, Bartender will try to conserve all the parameters provided in the input and use approach number 2. The user should carefully think about the best possible mapping within the Martini parameterization rules to avoid this scenario.

How Bartender works

In few words, Bartender will prepare and run a semiempirical QM or a classical atomistic MD simulation using the xtb program. For each bonded term requested, it will obtain a histogram with the frequency distribution for that bonded term in the resulting trajectory, when mapped to CG beads. It will use the Boltzmann probability distribution to convert those frequencies into energies, and then fit the target potential/s to those energies.

Bartender options

Although the basic command should be sufficient in most cases, Bartender has a large amount of flags that can be used to control its behavior. A full list of the available flags can be seen by issuing the command:

bartender -help

Some of the most commonly used flags are listed and discussed briefly below

1. -verbose X or -v X Where X is an integer. Sets the verbosity level for both the output to the standard output and the standard error. The default 1 should suffice in most cases.
2. -removeanharmonic Attempts to remove anharmonicities from the initial frequencies histograms. This can be useful in cases where the distribution is multimodal and has several high energy points which may shift the equilibrium value. While it is not to be used as a default setting, it may be required in tricky cases, particularly angles with soft potentials.
3. -histcutoff X Where X>0 and X<1. Removes from the frequency histogram any bin with frequency less than X times the frequency of the most populated bin. This is also to allow bartender to better fit a particular distribution, and not to be used as default. It was tested on some systems and, for some bonds and angles, it produced good enough values while discarding less points that the -removeAnharmonic flag.
4. -solvent Set a dielectric constant which is compatible with the solvent required for the simulation. Common values are 80 (water), 21 (acetone) and 10 (octanol).
5. -owntraj trajfile Causes Bartender to use the trajectory in trajfile instead of running a simulation. Supported formats are multi-PDB, multi-XYZ, DCD (NAMD) and XTC.
6. -method METHOD Defines the method to be used for the MD simulation. METHOD can be GFN0 GFNFF or GFN2 (default).
7. -time X The simulation time for the MD, in ps. Must be an integer.
8. maxiters Refinement of the histograms by iterative fitting. Default is 0 and produces reasonable eq values/force constants, but it may be explored to see if fits improve for particular bonded parameters.

The Bartender output

Bartender produces several output files

• gmx_out.itp As mentioned, this is the main output file, which contains the determined parameters. Each parameters is followed by a comment, containing the RMSD between the fitted function and the energies derived from the frequencies histogram.

• Beads.pdb Is a PDB to visualize the atoms to beads mapping provided by the user in the input file. In this PDB, the residue ID field of each atom corresponds to the bead to which it belongs. Additionally, the b-factor of each atom is interpolated from 0 to 99 depending on the corresponding bead number. Thus, a molecular visualization program, such as PyMOL or VMD can be used to see the mapping, with colors.

• For each fitted function, a png file is produced that shows a plot of both the energies obtained from the frequencies histogram, and the corresponding values of the function.

• Similarly, xvg-formatted files are produced with 3 columns: The x axis, in either degrees (for angles) or Angstroms (for bonds), the histogram-obtained energies and the corresponding values of the fitted functions.

• In addition to the output files, Bartender outputs information to both stdout and stderr The amount of information thus printed can be controled with the -verbose or t-v flags (which are equivalent).