The MDFF plugin provides commands for setting up and analyzing molecular dynamics flexible fitting simulations, i.e., simulations in which an atomic structure is flexibly fitted into a density map. Traditional MDFF simulations fit structures into a cryo-EM density map, while the newer xMDFF method can be used for the refinement of low-resolution x-ray crystallography structures.

MDFF Structure in Density

Getting started

For a description of the MDFF method, required software, related publications, related updates, etc., please see the MDFF website. The following reference provides a practical guide to MDFF:

Molecular Dynamics Flexible Fitting: A practical guide to combine cryo-electron microscopy and X-ray crystallography.
Leonardo G. Trabuco*, Elizabeth Villa*, Eduard Schreiner, Christopher B. Harrison, and Klaus Schulten. Methods, 49, 174-180, 2009.

MDFF tutorial: For tutorials related to the MDFF method, click here.

Getting help: Any questions, bug reports, feature requests, suggestions or comments related to MDFF should be sent to the VMD mailing list.

Acknowledging MDFF in publications

Please cite the following reference in any work that applied MDFF:

Flexible fitting of atomic structures into electron microscopy maps using molecular dynamics.
Leonardo G. Trabuco*, Elizabeth Villa*, Kakoli Mitra, Joachim Frank, and Klaus Schulten. Structure, 16, 673-683, 2008.

Please cite the following reference in any work that applied xMDFF:

xMDFF: Molecular dynamics flexible fitting of low-resolution X-Ray structures.
Ryan McGreevy*, Abhishek Singharoy*, Qufei Li, Jingfen Zhang, Dong Xu, Eduardo Perozo, and Klaus Schulten. Acta Crystallographica, D70, 2344-2355, 2014.

* Equal contribution.

MDFF developers

The MDFF plugin was written by Leonardo Trabuco, Elizabeth Villa, and Ryan McGreevy.

MDFF commands

The current version of the MDFF plugin provides both text commands and a graphical user interface. You first need to load the MDFF plugin by typing package require mdff in the VMD text console or the Tk Console. Typing mdff will print the available subcommands:

Usage: mdff <command> [args...]
  ccc        -- calculates the cross-correlation coefficient
  check      -- monitors the fitting via RMSD and CCC
  constrain  -- creates a pdb file for restraining atoms
  delete     -- deletes volume corresponding to atomic structure
  edges      -- creates a map with smooth edges
  fix        -- creates a pdb file for fixing atoms
  griddx     -- creates a map for docking
  gridpdb    -- creates a pdb file with atomic masses in the beta field
  setup      -- writes a NAMD configuration file for MDFF
  sim        -- creates a simulated map from an atomic structure

Typing each command will print the corresponding usage information (e.g., type mdff sim to get the usage information of the sim subcommand.

mdff ccc

Usage: mdff ccc <atom selection> -i <input map> -res <map resolution in Angstroms> ?options?
  -spacing <grid spacing in Angstroms> (default: 1.0)
  -threshold <x sigmas>
  -allframes (average over all frames)

mdff check

Usage: mdff check ?options?
  -mol <molid> (default: top)
  -frames <begin:end> or <begin:step:end> or all or now (default: all)

  -rmsd -- calculate the RMSD with respect to the refence structure
  -rmsdseltext <selection text for calculating the RMSD> (default: backbone)
  -refpdb <pdb file> -- reference for RMSD calculation (default: frame 0)
  -rmsdfile <file to write RMSD> (default: none)

  -ccc -- calculate cross correlation coefficient
  -map <input map> (required by -ccc)
  -res <map resolution in Angstroms> (required by -ccc)
  -spacing <grid spacing in Angstroms> (default: 1.0)
  -cccseltext <selection text for calculating the cross correlation (default: protein or nucleic)
  -cccfile  <file to write cross correlation> (default: none)
  -threshold <x sigmas>

mdff constrain

Usage: mdff constrain <atomselection> -o <pdb file> ?options?
  -col <column> (default: B)
  -k <force constant in kcal/mol/A^2> (default: 10.0)

mdff delete

Usage: mdff delete <atom selection> -i <input map> -o <output dx map> ?options?
  -res <target resolution in Angstroms> (default: 10.0)
  -spacing <grid spacing for "mask" map in Angstroms> (default: 1.0)
  -allframes -- average over all frames

mdff edges

Usage: mdff edge -i <input map> -o <output dx map> ?options?
  -kernel <Gaussian kernel> (default: 3.0)

mdff fix

Usage: mdff fix <atomselection> -o <pdb file> ?options?
  -col <column> (default: O)

mdff griddx

Usage: mdff griddx -i <input map> -o <output dx map> ?options?
  -threshold <value> (default: 0)

mdff gridpdb

Usage: mdff gridpdb -psf <input psf> -pdb <input pdb> -o <output pdb> ?options?
  -seltext   -- atom selection text  (default: noh and (protein or nucleic))

mdff setup

Usage: mdff setup -o <output prefix> -psf <psf file> -pdb <pdb file> -griddx <griddx file> ?options?
  -gridpdb  -- pdb file for docking (default: -pdb)
  -diel     -- dielectric constant (default: 80; 1 with -pbc)
  -temp     -- temperature in Kelvin (default: 300)
  -ftemp    -- final temperature (default: 300)
  -gscale   -- scaling factor for the grid (default: 0.3)
  -extrab   -- extrabonds file (default: none)
  -conspdb  -- pdb file with constrained atoms (default: none)
  -conscol  -- force constant column in conspdb (default: beta)
  -fixpdb   -- pdb file with fixed atoms (default: none)
  -fixcol   -- column in fixpdb (default: occupancy)
  -scal14   -- 1-4 scaling (default: 1.0)
  -step     -- docking protocol step (default: 1)
  -parfiles -- parameter file list
  -minsteps -- number of minimization steps (default 200)
  -numsteps -- number of time steps to run (default: 500000)
  -margin   -- extra length in patch dimension during simulation (default: 0)
  -pbc      -- use periodic boundary conditions (for explicit solvent)
  -gbis     -- use generalized Born implicit solvent (not compatible with -pbc)
  -dir      -- Working Directory (default: current directory)
  --lite    -- use girdforcelite, a faster but less accuracte calculation of mdff forces
  --gridoff  -- turn off gridforces, so no mdff forces are applied
  --imd     -- turn on Interactive Molecular Dynamics (IMD)
  -imdport  -- port for IMD connection
  -imdfreq  -- timesteps between sending IMD coordinates
  --imdwait -- wait for IMD connection
  --imdignore -- ignore steering forces from VMD
  --xmdff   -- set up xMDFF simulation. The following options apply to xMDFF only.
  -refs     -- reflection data file (mtz or cif). Required for xMDFF
  -refsteps -- number of refinement steps between map generation (default: 20000)
  -crystpdb -- text file (can be PDB) with PDB formatted CRYST line to supply symmetry information (default: none, but recommended)
  --mask    -- clean generated maps by applying a binary mask around structure (default: off)
  -mask_res -- resolution of mask density in Angstroms (default: 5)
  -mask_cutoff -- cutoff distance of mask density in Angstroms (default: 5)
  --bfs     -- calculate beta factors during every map generation step (default: off)
  -averagemap -- generate density maps which are averaged from multiple previous steps (default: 0 (off). 1 for on. One entry per map defined in -refs)
  -bsharp   -- apply beta factor sharpening (or smoothing) to the map(s) (default: 0 (off). Negative values for smoothing, positive for sharpening, 'a' for automatic determination (sharpening only))

mdff sim

Usage: mdff sim <atomselection> -o <output map> ?options?
  -res <target resolution in Angstroms> (default: 10.0)
  -spacing <grid spacing in Angstroms> (default: 1.0)
  -allframes (average over all frames)


The mdff plugin can also be used through a graphical user interface, found in the "Modeling" section of the VMD "Extensions" menu. This interface provides many of the same features found in the command line version of the plugin in a more user friendly package. The GUI can be used to easily set up both MDFF and xMDFF simulations, as well as launch, connect to, and analyze interactive MDFF simulations.

MDFF Files subsection of MDFF GUI
MDFF Files subsection of the MDFF GUI
The "MDFF Setup" tab of the GUI contains sections for setting up MDFF and xMDFF simulations. The "MDFF Files" subsection guides the user through creating the files necessary for running a MDFF simulation. The user must select an already loaded molecule with a PSF and PDB file. The starting structure for the simulation will be whatever the current frame of that molecule is. Users are also required to select a density map to which the structure will be fit (unless you are performing xMDFF or turn off grid forces in the "Simulation Parameters" section). You may add as many density maps as you want, with each having their own gridpdb selection text and scaling factor. The gridpdb selection text is for selecting the atoms that will be affected by the density-derived potential during the fitting. Selections for any fixed atoms can be given in the 'Fixed PDB selection text' box. The 'Simulation Output Name' will give the NAMD configuration file and trajectory output files their name. The 'Simulation Output Step' can be used for setting up multi-step fitting workflows. Any number in this field greater than 1 will cause NAMD to automatically use the previous step as a starting point for the next simulation. This subsection also contains check boxes for creating the restraint files useful in preventing overfitting.

Simulation Parameters subsection of MDFF GUI
Simulation Parameters subsection
of the MDFF GUI
The "Simulation Parameters" subsection contains options for adjusting the paramaters (e.g. Temperature, Time Steps) of the NAMD simulation. You may want to check the box labeled 'gridforcelite', which will tell NAMD to use a faster, but slightly less accurate, interpolation for calculating the forces derived from the density map. You can also choose to turn off grid forces entirely. In this section you can also select the environment of your MDFF simulation, e.g. vacuum, explicit solvent with periodic boundary conditions, or a generalized Born implicit solvent.

xMDFF subsection of MDFF GUI
xMDFF subsection off the MDFF GUI
The "xMDFF" subsection contains options specific to xMDFF (MDFF for low-resolution X-ray crystallography), such as selecting the required reflections file to use for generating density maps during refinement. Similar to adding density maps in the "MDFF Files" subsection, you can add as many maps as you wish, using the same or different reflection files, and each with their own parameters. Parameters include masking the density around the structure, computing average maps (the generated density map will be an average of the previous 5 frames), and sharpening or smoothing the density.

IMD Parameters subsection of MDFF GUI
IMD Parameters subsection
off the MDFF GUI
The "IMD Parameters" subsection is used for setting up interactive MDFF or xMDFF simulations, allowing the user to visualize and manipulate the structure in real-time as the NAMD simulation runs. Additional information on interactive MD can be found on the IMD website or in the MDFF tutorial. The 'Wait for IMD Connection' causes NAMD to wait until you have connected VMD to the simulation before beginning. 'Ignore IMD Forces' tells NAMD to ignore any steering forces that could be applied through VMD (e.g. use this setting if you only wish to observe your simulation). The IMD Port is the computer network port over which VMD and NAMD communicate. IMD Frequency sets the frequency of NAMD simulation steps sent from NAMD to VMD. IMD Keep Frames sets how many of the steps NAMD sends to VMD are saved in VMD. The simulation steps will still be saved to a .dcd regardless, but you may want to save them in VMD immediately as they come in. Be aware that this may use a significant amount of computer memory. The next settings, IMD Server and Processors, are related to where and how the NAMD simulations will be run. By default, the simulations are run on your local machine by calling the namd2 command with the selected number of processors. This assumes that namd2 is on your computer's PATH. If you wish to adjust how NAMD is called or add additional server definitions, you can add them to a MDFF GUI settings file. To see how the default server is set, save your settings file and open the file with a text editor. You should see near the bottom something like:
MDFFGUI::gui::add_server "Local" { } {
maxprocs 12
namdbin {namd2 +p%d}
jobtype local
timeout 20
numprocs 12

Here you can modify the "Local" server, or create a new entry and name it something unique (i.e. not "Local"). You can change how namd2 is called in the namdbin setting, the default number of processors to use, and the timeout (in seconds) for how long VMD should wait after attempting to contact NAMD before giving up.

Once all of the settings are set, the user should select the "Generate NAMD files" button to create the NAMD configuration files and any associated files for the simulation.

Interactive MDFF tab of MDFF GUI
Interactive MDFF tab of the MDFF GUI
The "IMDFF Connect" tab is used for launching, connecting to, stopping, and real-time cross correlation analysis of interactive simulations. Before (or after) connecting to a running IMDFF simulation, you can open the 'Cross Correlation Analysis' subsection in the IMDFF Connect tab to perform real-time analysis of your fitting. To do so, check the 'Calculate Real-Time Cross Correlation' box. You can also set the atom selection for the piece of the structure you wish to analyze, as well as the resolution of the map. You can also set a threshold value, where any density values less than the threshold will not be included in the analysis. The cross correlation value for each simulation frame will be graphed in the area at the bottom of this tab. This is a convenient way of determining how well your fitting is progressing and whether the simulation has converged.

All of the settings found in the MDFF GUI can be saved and later loaded from the "File" menu.