GUI-BioPASED: Reference Manual

General Information

• About BioPASED
• GUI-BioPASED – GUI for BioPASED
• Supported Web Browsers
• Working with Web Program
• User Sessions
• Multilingual Support

Setting up Parameters

• Project Parameters
• Structure & Energy
• Molecular Dynamics
• Force Field
• Solvation & Counter-ions
• Trajectory Analysis

Actions

• Generating Input Files
• Clearing Parameter Values

Additional Sections

• PDB Validator
• Setting up BioPASED
• Links Page

General Information

The section contains general information about programs named BioPASED and GUI-BioPASED, their execution environment and usage principles.

About BioPASED

The BioPASED program is designed for computation tasks with three-dimensional protein and nucleic acid structures developed for structure analysis, structure optimization according to conformation energy, statistical analysis of conformational dynamics of the structure and free energy calculation for the biopolymer's conformation. The mathematical model in the frame of classical molecular mechanics method is used. Atoms are treated as classical point-size particles, interacting with each-other and the environment by the complexes of covalent and non-covalent interatomic intramolecular forces according to the defined physical models. The physical model of forces is defined by the force field model for interatomic interactions. Program is designed to work with protein molecules consisting of 20 types of natural aminoacid residues and nicleic acid molecules, DNA and RNA, consisting of 4 types of natural nucleotides and several types of minor nucleotides that can be observed in natural t-RNA. Maximum summary number of atoms in protein molecule, nucleic acid or their complex should not be greater than 10000. This allows to work with the most known protein molecules and nucleic acid fragments.

The program supports Linux and Microsoft Windows operating systems.

GUI-BioPASED – GUI for BioPASED

The GUI-BioPASED program is designed to create control files for the BioPASED program in an interactive mode. An interactive mode here means using different controls user is familiar with, with the corresponding titles, instead of providing parameters manually in a text mode, where the exact knowledge of keywords is required, and also the strict formatting is assumed. The program also basically checks input values to be of the required type and to be in the allowed value range. The program creates a command file (for Windows and Linux operating systems), that allows to start computations on user's local machine immediately. Operating system is detected automatically, that allows users not to think of operating system specific tweaks.

Supported Web Browsers

The GUI-BioPASED program has a complete support of all wide-spread web browsers: Microsoft Internet Explorer (version 6.0 and above) and all browsers based on its core (e.g., Maxton), Mozilla FireFox (versions 2 and 3, including Linux versions), Opera, Google Chrome. Some minor difference in page layout and controls' look-and-feel could be noticed, but they won't interfere program usage however.

Working with Web Program

Right after opening the program in a web browser's window one can start to work with it. The main menu located on the left allows to switch between different parameter groups. These groups were created for user's convenience and are in common subject area. One can fill parameters' values sequentially, using «Next Page» button, or in arbitrary order. All intermediate data will be stored. After all values are filled in, the archive containing all the control files should be generated. The archive includes a command file to lauch the BioPASED program, a main control file and additional files if they are required. The archive has tar.gz format and can be opened with proper archivers both in Windowsand Linux operating systems.

User Sessions

To identify users program uses its own session mechanism based on users' IP-addresses (both external and internal if it resolves) and unique identifiers stored in cookies. Therefore for convenient work cookies should be enabled and program should be allowed to write them. No data except applied directly to the program will be written.

User session expires in 15 minutes. So if user diverts his attention away for more than this time period all data entered may be lost. The same thing may happen if the program is not able to work with cookies – in this case the unique identifier will be lost, the program will allocate a new one and a new session will be initialized.

Furthermore one can manually reset all the parameters to their initial values. In all other cases, e.g. on creating control files, data entered won't be reset.

Multilingual Support

The GUI-BioPASED supports multiple languages. At this moment only English and Russian languages are supported, however more can be added at administrator's discretion. English language is the default program language. Language switching is performed by clicking the icon with the corresponding national flag located in the top right corner of the program's layout. A language title hint is shown on moving the mouse over the icon. The information about the selected language is stored in cookies and is restored automatically on subsequent program runs.

Setting up Parameters

This section contains information about program parameters, ranges of acceptable values and links between parameters.

Project Parameters

• Project Name: general project name used in file names. This parameter is mandatory. By default the title «UntitledProject» is assigned.
• Working Directory: full path to directory on user's local machine where PDB-file is located and where the result files will be written in. This parameter is mandatory. By default the value of current working directory is assigned, that is «./».
• Working PDB-file: name of PDB-file that is the source file for computations. It must be located in the working directory. This parameter is mandatory, but has no default value. Therefore one must enter at least one value before generating input files, for this parameter. The parameter corresponds to the «-с» command-line argument of the BioPASED.

Structure & Energy

• Hydrogen Atoms: allows to specify the mode of how the information about hydrogen atoms is gained. By default the hydrogen restore module is used. If hydrogen atoms exist partially these atoms are ignored and are completely restored according to polymer residues topology library. The restoration of missing heavy atoms of aminoacid side chains is performed automatically by comparing PDB-file read with residue topology in the library. The reading from source structure mode can also be specified if it contains all the hydrogen atoms; this corresponds to specifying the «$Hread» keyword in the control file.
• Molecule Optimization: this parameter specifies whether all the molecule will be used for optimization (which corresponds to the «$FullProtMD» keyword of the control file), or the molecule fragments (which corresponds to the «$MovingRes» keyword). If the «Selected Atoms Only» option is selected, one should specify the segments to be optimized (see «Segment Definition File»). By default all the molecule is optimized.
• Calculate Energy for Source Structure: specifies whether to perform energy calculation for the source structure. By default it is performed. This parameter corresponds to the «$EngCalc» keyword of the control file.
• Energy Minimization using Local Optimization Method: specifies whether to perform energy optimization using local optimization method. During the computation process the file named  MolName.molEnOpt.pdb will be created – this is the result of molecule's structure optimization. By default the optimization is performed. This parameter corresponds to the «$EngOptim» keyword of the control file.
• Minimization Step Count: specifies the number of steps program takes to minimize energy using local optimization method. Minimization step includes a local minimum calculation in single descent direction for a multiple arguments function. Acceptable value range is from 1 to 999. By default 10 steps are performed. The value of 1 is reasonable if the previously optimized structure is taken for the computations. This parameter corresponds to the «$nOptStep» keyword of the control file.
• Segment Definition File: allows to edit segments to be optimized in a separate editor. Segment is designated by specifying the first and the last residue accoring to the serial number of the residue in the protein molecule. Segments to be optimized are stored in the separate input file that is added to the archive to be downloaded by the user. The file name is passed to the BioPASED using «-mv» command-line argument.

Molecular Dynamics

• Molecular Dynamics Simulation: a general parameter that specifies whether the optimization of the molecule using molecular dynamics method will be performed. If it won't all the subsequent parameters would become disabled and would not be used. By default the molecular dynamics simulation is enabled. This parameter corresponds to the «$doMDyn» keyword of the control file.
• Initial Temperature of Molecule, K: specifies the initial temperature of the molecule in the Kelvin scale, used to initialize the initial conditions of atoms' velocities' distribution for the molecular dynamics method. Acceptable value range is from 1 to 1000. By default the value of 10 is used. This parameter corresponds to the «$initMDTemp» keyword of the control file.
• Thermostat Temperature, K: specifies the initial temperature of the environment (thermostat) in the Kelvin scale, where the molecule is located in. Acceptable value range is from 1 to 1000. By default the value of 100 is used. This parameter corresponds to the «$bathMDTemp» keyword of the control file.
• Modelling Timestep, ps: specifies the intergration timestep in picoseconds. Acceptable value range is from 0.0001 to 0.002. Recommended value range is from 0.001 to 0.002. By default the value of 0.001 is used. This parameter corresponds to the «$mdStepTime» keyword of the control file.
• Modelling Step Count: specifies atomic movement equation integration step count for the molecular dynamics method with the current integration timestep specified by previous parameter. The minimum value is 1 step. By default the value of 1000 steps is used, however one is very likely to raise it. This parameter corresponds to the «$runMDnstep» keyword of the control file.
• Structure Save Interval, in steps: specifies the number of steps after which the molecule's structure snapshot is written to files named like MolName.molMdRes0001.pdb ... .0xxx.pdb. The minimum value is 1 step. By default the snapshot is written every 100 steps. This parameter corresponds to the «$nwtra» keyword of the control file.
• Simulated Annealing: allows to perform a molecule optimization using simulated annealing method. If this mode is enabled a simulated annealing protocol must be created (see below). By default this mode is disabled. This parameter corresponds to the «$MDSA» keyword of the control file.
• Annealing Protocol: allows to create a simulated annealing protocol in a separate editor. One line of the protocol contains 5 parameter values:
  1. modelling time steps, or time in integration steps;
  2. temperature of the molecule which it approaches to during the molecular dynamics simulation of specified duration;
  3. weight coefficient for the repulsive branch of the Van-der-Vaals potential;
  4. weight coefficient for the hydrogen bonds between atoms in the aminoacid residues' backbone;
  5. weight coefficient for the hydrogen bonds between side chain atoms and any other atoms.
  Simulated annealing protocol is stored in the separate input file that is added to the archive to be downloaded by the user. The file name is passed to the BioPASED using «-sa» command-line argument.
• Phosphate Charge Scale: allows to specify a scale for a charge of phosphate groups. Acceptable value range is from 0.0 to 1.0. By default the value of 1.0 is used. This parameter corresponds to the «$qPhosphSc» keyword of the control file.
• S-S bond formation: allows to select a mode which will be used by the program to create S-S bonds between Cysteine residues. Automatic bond formation means that all Cysteine residues are assumed to form a potential S-S bond, and the program searches for those that have S-atoms close enough and then forms a bond between them. PDB-based bond formation means that such behaviour is applied only to those Cysteine residues that were explicitly marked by "CYX" code. Residues with the code "CYS" will never form bonds even if they are close enough. By default the automatic mode is used. This parameter corresponds to the «$defSSbond» keyword of the control file.

Force Field

• Use SHAKE Method: specifies how to use the SHAKE method for keeping valence bonds constant. By default this method is not used. This parameter corresponds to the «$shake» keyword of the control file.
• Hydrogen Bond Factor: specifies maximum energy of hydrogen bonds (in kcal/mol). Acceptable value range is from 0.0 to 5.0. By default the value of 2.0 is used. This parameter corresponds to the «$hBond128» keyword of the control file.
• Atom Positional Restraints: specifies a harmonic potential for atoms' origins. If this mode is enabled one should describe segments of the molecule to be restrained (see below). By default this mode is disabled. This parameter corresponds to the «$harmAt1PosRst» keyword of the control file.
• Restraint Definition File: allows to specify segments to be restrained in a separate editor. One line of the file contains 4 parameter values:
  1. number of first residue in the molecule;
  2. number of last residue in the molecule;
  3. a rigidity constant of the segment (in kcal/A²) for the harmonic potential K_h*(r_i‑r0_i)², applied to atom i specifying a positional restraint with an origin in r0_i;
  4. restraint type: PBB (protein backbone), NAB (nucleic acid backbone) or ALL (all segment atoms).
  The information about segments' positional restraints is stored in the separate input file that is added to the archive to be downloaded by the user. The file name is passed to the BioPASED using «-r» command-line argument.
• Additional Positional Restraints (with distance): specifies an additional harmonic potential for the distance between atom pairs. If this mode is enabled one should describe atom pairs to be restrained, distances and rigidity constants for the harmonic potenrial (see below). By default this mode is disabled. This parameter corresponds to the «$distRestrA2» keyword of the control file.
• Additional Restraint Definition File: allows to specify atom pairs with additional distance-based positional restraints in a separate editor. One line of the file contains 4 parameter values:
  1. number of first atom in the molecule;
  2. number of last atom in the molecule;
  3. a distance between atoms;
  4. a rigidity constant for the harmonic potential.
  The information about atoms with additional positional restraints is stored in the separate input file that is added to the archive to be downloaded by the user. The file name is passed to the BioPASED using «-d» command-line argument.

Solvation & Counter-ions

• Solvation Model: selects a solvation model to be used in simulation, Gaussian hydrate shell in the force field (corresponds to the «$SolvGS» keyword) or water shell (corresponds to the «$SolvateExWat» keyword). The last requires specifying water shell width (see below). Water molecules are included to the list of molecule's segments to be optimized. By default the Gaussian shell is used.
• Water Shell Width, A: specifies water shell width (in Angstroms) in case the water shell solvation model was selected. Acceptable value range is from 3.0 to 7.0. By default the value of 3.5 is used. This parameter corresponds to the «$SolvateExWat» keyword of the control file.
• Water Bridges: enables the «Water Bridges» solvation model (only when the Gaussian shell is selected as the primary solvation model). The file named MolName.watBrgSolvXYZ.pdb is created. It contains coordinates of water molecules' atoms that form water bridges between polar atoms of the molecule. By default this model is not used. This parameter corresponds to the «$SolvWbr» keyword of the control file.
• Write Solvent-Accessible Surface of Molecule to File: enables creation of the file named MolName.molSASXYZ.pdb,which contains coordinates of solvent-accessible surface patches. This mode can be enabled only when the «Water Bridges» solvation model is selected. By default this mode is disabled. This parameter corresponds to the «$writeSASxyz» keyword of the control file.
• Neutralizing Counter-ions: enables compulation of neutralizing counter-ions' positions on the biopolymer's surface. Counter-ions' coordinated are written to the file named MolName.coIonSheLXYZin.pdb. Counter-ions are included to the list of the atoms to be optimized. By default this mode is disabled. This parameter corresponds to the «$coIonShell» keyword of the control file.

Trajectory Analysis

• Molecular Dynamics Trajectory Analysis: enables computation of quasiharmonic modes of maximum amplitude oscillations based on calculation and analysis of the molecular dynamics trajectory. Computation of an average dynamic structure is performed along with computations of three quasiharmonic modes of maximum amplitude. Results are stored in PDB-format files. By default this mode is disabled. This parameter corresponds to the «$EssModeAnalys» keyword of the control file.
• Free Energy Calculation in Quasistable Conformation: enables computation of free energy of the biopolymer in a quasistable conformation. Computation of the molecular dynamics trajectory in the phase space, computation of normal quiasiharmonic oscillation frequencies, computation of an entropy in quisiharmonic oscillators' approximation. Molecular energy results along the molecular dynamics trajectory are stored in the file named MolName.engTable.dat. By default this mode is disabled. This parameter corresponds to the «$FreeEnergy» keyword of the control file.

Actions

Generating Input Files

The menu item named «Generate Input Files» is responsible for a creation of an archive containing control files for the BioPASED, which is suggested to be downloaded by user to his local machine. Files are packed into a tar.gz archive which is familiar to the most non-specialized archivers. After downloading the archive with files which is usually several-kilobytes-sized, one should unpack the files to the working directory (specified in the project parameters) and run a command file (for Windows this is a file with .bat extension, for Linux this is a file with .sh extension).

Before control files are created the program checks all the parameters' input values. If some of the required values are missing, or the input value's type does not meet the parameter's type, or the value falls out of the acceptable range, the parameter is marked as erroneous. If some erroneous parameters were found, instead of archive download prompt the list of such parameters is generated with the suggestions of how to fix their values. After fixing all the errors one can check parameter's input values again and, if no more errors exist, will be prompted to download an archive with control files.

Clearing Parameter Values

One may need to clear all the input values for parameters to their default values instead of changing each value manually. A special menu item named «Clear All» is designed for that. Before the action is executed one will be prompted to confirm the purge in the case this menu item was selected by mistake.

Additional Sections

PDB Validator

To determine whether the BioPASED program will work with user's PDB-filed, there is a PDB validation function. File to be validated is uploaded to the server and analyzed. If it contains critical errors, their minute description is displayed. If errors are insignificant, the validation program corrects them and suggests to download a valid PDB file. Besides correction of insignificant errors (see below) the validation program removes all the information that is not parsed by the BioPASED program (in particular, remarks and heteroatoms; in the last case there may be raised some errors that are mentioned below). If there are alternate atom coordinates program stores only atoms of group A, and if there are multiple models program stores only model 1 atoms. Therefore do not replace the original PDB file with the valid one, but save it separately. Program also searches for Cysteine residues that can potentially form an S-S bond and allows user to decide whether the particular bond would be formed (this choice has an effect only in PDB-based S-S bond formation mode, see above). The valid PDB file is packed into a tar.gz archive which is familiar to the most non-specialized archivers, and should be unpacked before use.

These errors are referred to as critical ones:

• Too many atoms: the BioPASED program can handle not more than 10000 atoms at that moment. If the number of atoms in the PDB file hits the limit, the program won't be able to load it. Some atoms should be deleted to enable the program to work with the file. The number of atoms is displayed in an error's text, and the number of heteroatoms is not included.
• Broken protein backbone in residue: this error is raised if some aminoacid does not contain four necessary atoms that form a protein backbone (these atoms are С, CA, N and O). The number of broken residue is displayed in an error's text. The PDB file must be edited and the break must be eliminated.
• Broken protein backbone in residue: this error is raised if some aminoacid does not contain four necessary atoms that form a protein backbone (these atoms are С, CA, N and O). The number of broken residue is displayed in an error's text. The PDB file must be edited and the break must be removed.
• Broken chain between residues: residue sequence numbering is disrupted. In this case the validator assumes that some residue is missing from the PDB file. This may occur if non-standard residues were written to the PDB file as the list of heteroatoms, that are not parsed. The residue numbers between which there is a disruption are displayed in an error's text. One must insert one or more missing residues by editing the PDB file, or, if the error is because of heteroatom removal, replace them with normal atoms of the proper residue.
• Undefined residue: there is a nucleotide residue or a modification group in the PDB file that program is not familiar with. This residue should be replaced with one of the common residues by editing the PDB file manually. Undefined aminoacid residues do not raise the error described (see below).
• Incomplete residue: there is a nucleotide residue or a modification group in the PDB file that has a heavy atom count not equal to the real atom count. Missing atoms with the correct coordinates should be added to the structure by editing the PDB file manually.

These errors are referred to as insignificant ones and are corrected automatically (the proper warning is used in this case):

• Invalid atoms' serial numbers: atom serial numbering must be sequential and start from 1. If it does not, the validation program corrects atom serial numbers. This error usually occurs in the PDB proceeding process (deletion of heteroatoms, aminoacid side groups etc.).
• Invalid residues' serial numbers: residue serial numbering must start from 1. Hovewer sometimes not all the residues are resolved within the PDB structure and several first residues are lost. In that case residue serial numbering does not start from 1 and this is corrected by the validation program. Incorrect residue numbering inside the chain leads to another, critical error - "Broken chain between residues". This correction is performed right before PDB file download therefore no warning is printed.
• Asterisks in atom names: in some PDB files atoms of the ribose and desoxyribose constain an asterisk in their names instead of a single quote. Such atom names are corrected automatically.
• Undefined aminoacid: if there is an unknown aminoacid with an intact backbone in the PDB file,the validation program corrects this error by replacing that aminoacid with known aminoacid and deleting all the atoms except four atoms forming the backbone. All other atoms will be restored by the BioPASED program during the computation process. Aminoacid may be selected to replace undefined one or it may not be replaced at all.

Program may also raise errors not connected with PDB structure:

• PDB File is empty: there are no atoms in the PDB file, or the file specified is not a PDB file.
• PDB File upload error: could not upload the file to the server. It might be an internal server error, or the file specified is too large.
• Program internal error: there was an internal error in the validator. This should never happen. If it did one is recommended to contact the program's developers.

Setting up BioPASED

Before running a command file generated by the GUI-BioPASED, one must install the BioPASED, the actual computing program. It can be done using «Download BioPASED» menu item by clicking the provided download link. User's operating system will be detected automatically. Windows users will be prompted to download an archive with the BioPASED for Windows, and Linux users will be prompted to download Linux-version of the program respectively. The program's setup information for the proper operating system is also shown.

For Windows operating system, setup process is the following:

1. Download the program distributive.
2. Install it into some directory, e.g., C:\BioPASED.
3. Add this path to the PATH environment variable, and also create another environment variable BIOPASEDHOME and assign this directory to it with addition of a trailing slash ("\"). It can be done from the Control Panel ("System"→"Advanced"→"Environment Variables").

In Linux operating system one must do the following:

1. Download the program distributive.
2. Install it into some directory, e.g., /home/yourname/biopased.
3. Add this path to the PATH environment variable, and also create another environment variable BIOPASEDHOME and assign this directory to it with addition of a trailing slash ("/"). It can be done by editing ".bash_profile" file (if you use Bash command processor). File may look like this:

   #!/bin/sh

   BIOPASEDHOME=/home/yourname/biopased/

   PATH=$PATH:home/yourname/biopased

4. Make sure that the file ".bash_profile" is executable (chmod +x .bash_profile). After changes you should restart your command processor.

Links Page

In the «Links» section administrator may publish links to any Web‑pages, that in his opinion may be useful for the GUI-BioPASED program users. It must be noted that these links are not in the direct contact with the program, and the program's developers take no responsibility for the contents located on the pages referenced by these external links.