Gromita Help

Gromita 1.06

Introduction

Gromita 1.06 is a Graphical User Interface (GUI) for GROMACS (v.3 and 4). It is writen in perl making extensive use of perl/tk achieving portability in a wide variety of operating systems and architectures. Gromita provides friendly to use buttons in a windows-based environment while maintaining a terminal mode for the experienced user.

Citation

Please cite:
Sellis D, Vlachakis D, Vlassi M. (2009) Gromita: A Fully Integrated Graphical User Interface to Gromacs 4. Bioinform Biol Insights 2009:3 99-102

Contents

1. Prerequisites
2. Installation
3. Description
4. Shortcuts
5. Getting started
6. GROMACS to Gromita migration guide (incl. implementations list to GROMACS v.4)
7. FAQ
8. Troubleshooting
9. Aknowledgments
10. Future Work

1. Prerequisites

1.a Hardware

Any computer capable of running GROMACS can run Gromita. A large screen (17') is preferable with high resolution, but not necessary

1.b. Software

Gromita is compatible with any UNIX type OS. We strongly recommend the popular distribution of Red Hat Fedora Linux. It only needs an installation of Perl (usually installed in most unix distributions) and the Tcl/Tk plug-ins. In order to perform molecular dynamics, GROMACS and the programs it depends on must be installed.


2. Installation

Gromita can be easily installed with the setup.pl installation perl script, which checks if all prerequisites are available and installs gromita.

  1. Install GROMACS and the programs it depends on
  2. Install Perl and Tcl using the system's Package Manager (in most Linux distributions it should be already installed)
  3. Install File::HomeDir using the CPAN module (you may have to install the CPAN module from the Package Manager)
      4. Here is how to check if the CPAN module is installed
      $>perl -e 'use CPAN;'
      if it is installed no error message should appear.
      Switch user to root in order to make perl/tk available to all users and invoke a CPAN shell
      $>su
      Password:
      #>perl -MCPAN -e shell
      (if you are using Ubuntu type instead: $>sudo perl -MCPAN -e shell and type your user password, not the root)
      install File::HomeDir:
      $>cpan>install File::HomeDir
      some installation and testing messages will follow, and when complete type quit to exit the CPAN shell
  4. Install Tk using the Yum Server (if you are using fedora).Just type:
      5. $>sudo yum install perl-Tk
      If you are using Ubuntu type instead:
      $>sudo apt-get install perl-Tk
  5. Extract the compresed file of Gromita (e.g in your desktop)
  6. Open a terminal and cd to the newly created directory
  7. Run the setup script:
    8. Note: In order to make  gromita available to all users  you must install it as root
    $>su
    Password:
    #>perl setup.pl
    Note: If you are using Ubuntu, type instead $>sudo perl setup.pl and when prompted enter your password (not the root)
    The setup script will check for the installed perl version, its modules, gromacs path e.t.c. Follow the instructions.
    $>perl setup.pl
    checking perl version...ok
    checking for required perl modules:
    File::HomeDir:  ok
    File::Spec:     ok
    Time::HiRes:    ok
    Carp:   ok
    Tk:     ok
    searching for GROMACS...ok
    counting processors...1
    searching for GROMACS dependences...FFTW: ok

    SETUP SUMMARY
    -----------
    Nothing missing
    Proceed with gromita installation? [y/n] 

  8. You will be then prompted for the gromita installation confirmation.
    Proceed with gromita installation? [y/n] y
    Starting installation
    Installation completed!
  9. Gromita is ready! Just type gromita and it will load

3. Description

Gromita's main window is shown in the following screenshot. It's main parts are: a Menubar, the Main Buttons on the left side of the screen, the Output Window on top, the Command Line Window bellow and the Indicators Bar.

Gromita screenshot

A. Menubar

File

The File menu contains the basic options for file handling, logging, printing and ending the program.
Opens a dialog window in order to select a pdb file
Saves a report of work done. If no report have been saved yet it does what a File -> Save as would do
Saves a report (.log file) containing the following information (not necessary all):
a) A title displaying the current date and time
b) The contents of the Command Line Window
c) The contents of the Output Window on top
Closes the currently loaded pdb file
By default no logging of Gromita's activities is done. If this option is selected a log file will be created or if it exists, information will be appended to the end of the file. By default the logfile created is named logfile.log. If there is a need of keeping information in a different file a new name can be specified in the Options -> Preferences menubutton.
Sends to the default printer a report containing the following information (not necessary all):
a) A title displaying the current date and time
b) The contents of the Command Line Window
c) The contents of the Output Window on top
Ends Gromita, but does not interrupt GROMACS if it is still working. It lets it continue working in the background. If there is a need of interrupting some GROMACS process there is the button Interrupt at the Indicators Bar.

View

Clears the Output Window
Clears the the Command Line Window
If a molecular viewer is defined, the pdb file loaded is shown. For defining a viewer see Options -> Preferences menubutton

Options

Opens a dialog window with the customizable values of Gromita.
The window also has three buttons. Save saves the user preferences not only for the current session, but also for future invocations of Gromita. Restore Defaults restores the default values for all entries.
Forces advanced mode only for the next command. In terminal mode the output is shown in a terminal window and can be useful in interactive commands. Normaly this option should not be used, when gromita guesses when gromacs will need feedback and automatically runs the command in terminal mode.
Opens a window showing the cpu % load for each processor and the overall average

Trajectory

Opens a dialog box with options for ngmx trajectory viewer
Opens a dialog box with options for the trjconv trajectory converter

Help

Opens this help file in a web browser.

B. Main buttons

Each button presents a basic step of a standard molecular dynamics simulation. By pressing each button a new window appears containing a variety of options. The options are grouped as basic and advanced. In the last row of each window they are three standard buttons Ok, Basic/Advanced and Cancel

By pressing the Ok button the corresponding GROMACS program is invoked with the options activated by the user options. By default the minimum necessary options are activated. Any other option is activated only when the user focus, press or change its value. 

By pressing the cancel button the window closes without any further action.

By pressing the Basic/Advanced button the window toggles between the basic and advanced mode hiding or showing the advanced options respectively.

Only one window of each main button can be open at any time.

Generate topology

Generate topology opens a window enabling the user to add hydrogens create coordinate and topology files from the pdb file loaded. It corresponds to pdb2gmx.

The basic options include a force field selector, and the filenames of the GROMACS coordinates and topology file. A checkbutton GROMACS help is also available that shows GROMACS help for the specific program in the output window.

Enlarge box

In this step a box of water with custom shape and size is defined or modified in which. Corresponds to editconf.

Solvate protein

Solvates a molecule in a box of water. Corresponds to genbox.

Prepare EM

Corresponds to grompp, GROMACS preprocessor. In this step the binary files are prepared for energy minimization alone.
Note that a Molecular Dynamics Parameter file (.mdp) is required. This file contains all information about the energy minimization alone e.g. step size, number of steps etc. One way to hundle such a file is by adapting a sample (.mdp) file from the gromacs site .

Energy Minimization

The actual energy minimization step. Corresponds to mdrun.

Prepare MD

Corresponds to grompp, GROMACS preprocessor. In this step the binary files are prepared for Molecular Dynamics.
Note that a Molecular Dynamics Parameter file (.mdp) is required in order to run MD simulations. A sample (.mdp) file can be obtained from the gromacs site.

Molecular Dynamics

In this step the molecular dynamics are run. Corresponds to mdrun.

C. Output window

Between  the output window and the command line window there is a divider that can be moved (by clicking and dragging the mouse button 1) changing the two windows' relative size.
output This is a read-only terminal-like window that shows Gromita's actions GROMACS output and some other information. Gromita's actions shown are loading or closing files and GROMACS invocations. A color code highlights GROMACS output warnings and errors which are also summed in a pop-up window.
moving around

The output-window has two scrollbars for scanning the text. For fast scanning the text the middle mouse button can be used. The text is "grabbed" and moved around. Keyboard arrow keys, page up and down have their well known function and can also be used for moving around.
selecting By pressing mouse button-1 and moving the mouse across the output window the text is selected and can be copied to any other application. Pressing shift and moving around with the arrow keys or page up and down can also be used.
refreshing By default the window will not erase any text, so a great amount of output could fill the memory and slow down the system. Practically this never happens so there is no worry of loosing output information nor downgrading performance. In case there is a need of erasing previous messages View -> Clear screen -> Output should be used.
advanced features There are some advanced features of the output window, rarely used, but nevertheless could prove very useful in some tasks. Right clicking when the mouse pinter is in the output window pops up a small menu which enables some basic operations.
File -> Exit: For fast quiting Gromita
Edit -> Copy: Copy selection
Edit -> Select All
Edit -> Unselect All
Search -> Find: Opens a dialog with options to find text in either forward or backward directions, using exact search or regular expressions and case sensitive or not. It can find only one or all occurrences
Search -> Find Next
Search -> Find Previous
View -> Goto Line...: Move to specified line of the text window
View -> Which line: Display line and column of cursor
View -> Wrap: Wrap text by word, character or remove word wrapping.

D. Command Line Window

This window displays the Gromita's actions as GROMACS commands in a terminal. Moving around, selecting text, refreshing the contents and its advanced features are as in Output Window.

E. Indicators Bar

Shows various status information. From right to left:

log on/of an indicator of whether a log file of the current actions is kept. Toggles from the menu File -> Start/Stop log or with the Control+l shortcut.
cpu % The percentage of cpu usage, refreshing every second. Useful for monitoring long lasting molecular dynamics.
Interrupt button A button for interrupting the currently running GROMACS program. If GROMACS hangs up or the user wishes to stop a process, by pressing the Interrupt button, a kill signal is sent to to the process. The button is active only when a process is running.
Progress indicators These indicators are shown only when the verbose option is selected from the Energy Minimization and Molecular Dynamics Main Buttons. There are three progress indicators, a progress bar showing the current step as a fraction of the total steps, a label showing an estimation of time left for the process to finish, and the percentage of it done. Estimations and step count is done by GROMACS.

4. Shortcuts

Menubar shortcuts are shown next to each command
Ctrl + o

File -> Open
Ctrl + s

File -> Save
Ctrl + a

File -> Save as
Ctrl + w

File -> Close
Ctrl + l

File -> Start/Stop log
Ctrl + p

File -> Print
Ctrl + q

File -> Quit
F1 Help

The shortcuts for output and command line windows are common for both. The following section describes shortcuts and bindings available for these windows as described in Tk::Text documentation:

In the descriptions below, word refers to a contiguous group of letters, digits, or characters, or any single character other than these.
  1. Clicking mouse button 1 positions the insertion cursor just before the character underneath the mouse cursor, sets the input focus to this widget, and clears any selection in the widget.  Dragging with mouse button 1 strokes out a selection between the insertion cursor and the character under the mouse.
  2. Double-clicking with mouse button 1 selects the word under the mouse and positions the insertion cursor at the beginning of the word.  Dragging after a double click will stroke out a selection consisting of whole words.
  3. Triple-clicking with mouse button 1 selects the line under the mouse and positions the insertion cursor at the beginning of the line.  Dragging after a triple click will stroke out a selection consisting of whole lines.
  4. The ends of the selection can be adjusted by dragging with mouse button 1 while the Shift key is down;  this will adjust the end of the selection that was nearest to the mouse cursor when button 1 was pressed.  If the button is double-clicked before dragging then the selection will be adjusted in units of whole words;  if it is triple-clicked then the selection will be adjusted in units of whole lines.
  5. Clicking mouse button 1 with the Control key down will reposition the insertion cursor without affecting the selection.
  6. The view in the widget can be adjusted by dragging with mouse button 2.
  7. If the mouse is dragged out of the widget while button 1 is pressed, the entry will automatically scroll to make more text visible (if there is more text off-screen on the side where the mouse left the window).
  8. The Left and Right keys move the insertion cursor one character to the left or right;  they also clear any selection in the text.  If Left or Right is typed with the Shift key down, then the insertion cursor moves and the selection is extended to include the new character.  Control-Left and Control-Right move the insertion cursor by words, and Control-Shift-Left and Control-Shift-Right move the insertion cursor by words and also extend the selection.  Control-b and Control-f behave the same as Left and Right, respectively.  Meta-b and Meta-f behave the same as Control-Left and Control-Right, respectively.
  9. The Up and Down keys move the insertion cursor one line up or down and clear any selection in the text. If Up or Right is typed with the Shift key down, then the insertion cursor moves and the selection is extended to include the new character.  Control-Up and Control-Down move the insertion cursor by paragraphs (groups of lines separated by blank lines), and Control-Shift-Up and Control-Shift-Down move the insertion cursor by paragraphs and also extend the selection.  Control-p and Control-n behave the same as Up and Down, respectively.
  10. The Next and Prior keys move the insertion cursor forward or backwards by one screenful and clear any selection in the text.  If the Shift key is held down while Next or Prior is typed, then the selection is extended to include the new character.  Control-v moves the view down one screenful without moving the insertion cursor or adjusting the selection.
  11. Control-Next and Control-Prior scroll the view right or left by one page without moving the insertion cursor or affecting the selection.
  12. Home and Control-a move the insertion cursor to the beginning of its line and clear any selection in the widget.  Shift-Home moves the insertion cursor to the beginning of the line and also extends the selection to that point.
  13. End and Control-e move the insertion cursor to the end of the line and clear any selection in the widget.  Shift-End moves the cursor to the end of the line and extends the selection to that point.
  14. Control-Home and Meta-< move the insertion cursor to the beginning of the text and clear any selection in the widget.  Control-Shift-Home moves the insertion cursor to the beginning of the text and also extends the selection to that point.
  15. Control-End and Meta-> move the insertion cursor to the end of the text and clear any selection in the widget.  Control-Shift-End moves the cursor to the end of the text and extends the selection to that point.
  16. The Select key and Control-Space set the selection anchor to the position of the insertion cursor.  They don’t affect the current selection.  Shift-Select and Control-Shift-Space adjust the selection to the current position of the insertion cursor, selecting from the anchor to the insertion cursor if there was not any selection previously.
  17. Control-/ selects the entire contents of the widget.
  18. Control-\ clears any selection in the widget.
  19. The F16 key (labelled Copy on many Sun workstations) or Meta-w copies the selection in the widget to the clipboard, if there is a selection.

5. Getting started

Create a directory in your home or Desktop for working with gromita, eg:

$> mkdir /home/user/work

change directory to work

$> cd work

invoke gromita

$>gromita

gromita is now loaded.

Go to Options -> Preferences and type your favourite molecular viewer (e.g. rasmol, pymol) and terminal (e.g. xterm, konsole) for gromita to use

Go to File -> Open and load a pdb molecule

Use the main buttons to perform your first simulation

6. GROMACS to Gromita migration guide

GROMACS program Gromita's Main Buttons  Options Table
pdb2gmx Generate topology View table
editconf Enlarge box View table
genbox Solvate protein View table
grompp Prepare EM
Prepare MD		 View table
mdrun Energy Minimization
Molecular Dynamics		 View table
trjconv View Trajectory View table
ngmx Convert Trajectory View table

Implementations of the Gromita GUI:

  • All implementations of the Gromita GUI for Gromacs v.4 are listed here

    • 7. FAQ

    1. How can I change the size of the Output window/Command line window?
        2. With the mouse click and drag the line dividing the output window from the command window
    2. How can I clear the contents of Output window/Command line window?
        3. Use the menu options View -> Clear screen
    3. What is the equivalent of a GROMACS command?
        4. Check the links in the 'GROMACS to gromita migration guide' section
    4. How do I become root (switch user)?
        5. use the command
        su (swich user), and type the root pasword $>su
        Password:
        #>
        If you are using Ubuntu, type sudo and when prompted enter your password (not the root):
        $>sudo commandname
    5. How gromita deals with older versions of Gromacs?
        Gromita was originaly designed around Gromacs v.3.3.1, but it has been refined for the recently released Gromacs v.4 (v.4.0.4). There are minor differences in the interface of the various gromacs versions, so gromita will probably work with older versions also, although some options might require the use of the advanced mode (terminal mode).

    8. Troubleshooting

    1.  Gromacs program seems to run while CPU load is very low (program halted)
    Use the interrupt button to stop execution. Select File -> Option -> advanced mode and try again.

    9. Aknowledgments

    Program development was supported by a grant from NCSR "Demokritos" ("Demoerevna-06")
    The Indicators bar on and off icons are from the "Clip Art Warehouse" (Graham Coupe http://www.clipart.co.uk/index.shtml)
    This help file was made with KompoZer and OpenOffice 2.4 and is adorned with some silk icons

    10. Future Work

    Future plans of the Gromita GUI will include the addition of features such as a "genion" and a "protonate" interface as well as a custom water model input window.