NAME

intro - introduction to yammp commands and molecular simulation.

DESCRIPTION

This section describes commands in the yammp package

Manual Page Command Syntax

Unless otherwise noted, commands described in the SYNOPSIS section of a manual page accept options and other arguments according to the following syntax and should be interpreted as explained below.

name [ -option ... ] -key value ...

where:

[ ]	surround an option or options
...	indicates multiple occurrences of the option
name	the name of an executable file
option	an optional argument which may take the form key value ...
key	a keyword which may a single character or a word. Most programs allow keywords to be abbreviated to the shortest unambiguous string.
value	a value to be associated with the keyword

All yammp programs require at least one argument on the command line. This means that typing the program name by itself is never enough. Instead, when you type just the name, you will get a command summary which should provide enough information to construct a proper command line.

Variables are italicized and commands and their arguments are written thus. File name arguments are written like-so. (We have not described the formatting since the outcome varies from browser to browser. Instead we rely on you recognizing the examples here later on in the manual pages.)

Molecular Simulation

There are four steps in molecular simulation with Yammp: Prepare the molecular mechanics model which consists of two parts: a more or less fixed part, the force field (first step) and a variable part, the coordinates for a starting conformation (second step). In a molecular simulation we manipulate the starting structure subject to the force field and produce new structures (third step) which we can examine (fourth step) or use as input to further simulations.

1. Assemble a force field description

In this step, a high level representation of the model that you wish to simulate is converted to a molecular mechanics representation using certain rules. The high level representation is typically a sequence. Some examples: a ribonucleic acid base sequence CUAGCGGAGGCUAG, a deoxyribonucleic acid sequence CAGGCTTTAC and a protein or peptide sequence MKQCAFVDEKRHNQY. These describe the molecules we wish to simulate in terms of the gross chemical structure or the sequence of monomeric units (residues) that make up the whole molecule. Such a description must be translated into the detailed molecular mechanics description that the simulation program needs. The molecular mechanics representation consist of lists of atoms that make up each residue, how the atoms are connected to one another and the parameters (such as force constants and equilibrium dimensions) of the mathematical function that describe the connections.

Yammp does not yet have a general purpose force field assembler but there are assemblers for specific model types. In the reduced representation model of DNA (3DNA), each base pair is represented as a plane consisting of three particles. To assemble the force field of such models you can use mkd3d. Another special purpose assembler exists for reduced representation ribonucleic acids which actually represents the bases in several ways. One way is to represent RNA as one particle per phosphate. To assemble such models you can use mksnad.

The assembled force field is saved in a descriptor file which can exist in either a binary or text format. The binary format is required by all Yammp programs while the text format can be viewed and modified. The program that converts between the two formats is called des. The descriptor file format is complicated but it is possible to write one from scratch for very simple models. In some cases it may be necessary to manually edit the descriptor created by an assembler.

2. Create a starting conformation

The starting conformation is a set of coordinates saved in an archive file. Yammp does not have a model builder but there are other ways to get a starting structure. For the reduced representation RNA model you can use mkr2cc or mkchainarc to generate random walk chains. For 3DNA modeling you can use mkd3c to generate DNA trajectories under different topological conditions. But for other models you probably have to use a model builder (building the model interactively or use a method like distance geometry) to generate a PDB file and convert that file to the archive format. The conversion is trivial and can be done in three short steps using a simple regular expression text editor.

Archive files can contain one or more records (such as a molecular dynamics trajectory) and each record may be a set of coordinates or velocities and other content types will be possible in the future. The archive file format is very simple.

There are two archive file formats: binary and text. Most of the yammp programs will use only the binary format. Files of this format can be converted using the program arc to the text format and back. The text version can then be converted to other file formats such as PDB. It is more convenient to use exam to write a PDB file from an archive record.

3. Run the simulation

Once you have assembled a force field descriptor and a starting archive you are ready for molecular simulation and you have a selection of methods. The specific method that you would use depends on what your simulation goals are and you are not confined to using only one method. You can also use more than one method in a single simulation.

In Energy Minimization the closest local energy minimum from the starting conformation is located. If the energy minimization is successful the energy of the new structure is lower than that of the starting structure. However chances are that there are other structures with lower energies. The structure with the lowest possible energy is called the global minimum energy structure. There are several energy minimization methods available in yammp. The simplest and most reliable method is Steepest Descent. This is almost always guaranteed to work but it is slow and it never converges. A more convergent algorithm is Conjugate Gradient and two variants are available. These methods are faster and more convergent than Steepest Descent but they are more sensitive to starting conditions and if you have a structure very far from equilibrium the procedures are likely to fail.

The Molecular Dynamics method is used to study the motion of a molecular system. The equations of motion are integrated over time producing a solution at each time step. The integration is approximated by a discrete iteration with a user-specified time step. The limiting factor here is the size of this time step which in typical systems is limited to about 1-2 fs. Any larger time step and the integration will be unstable. One advantage of using reduced representation models is that larger time steps can be tolerated, which allows much larger systems to be studied. Two varieties of molecular dynamics are available: Newtonian and Langevin and two integration algorithms are available: Beeman and Verlet.

In the Monte Carlo method the molecular system moves through phase space (in contrast to Molecular Dynamics where the molecules move over time). An atom is chosen at random and moved in a random direction by a random displacement. The change in energy due to the trial move is calculated and the move is accepted at a probability proportional to the Boltzmann factor, i.e., this method allows uphill moves in which the energy increases.

Although there are only three simulation methods they are capable of many variations. One would also typically use more than one method in a single simulation. For example, in structure refinement with a very bad starting structure one would start with the Monte Carlo method to remove the worst structural irregularities, then move on to a simple Energy Minimization method and as a better structure is obtained the refinement can be finished with a more convergent Energy Minimization method.

The molecular simulation module in yammp is called mimesis. To run this program you need to supply a descriptor file and an archive file. You can write the new structures in a new archive file or append them to the input archive file. You would then direct the path of the simulation using the Yammp-Shell to script the calculation.

4. Examine the outcome

The outcome of a simulation might be a single set of coordinates, of a refined structure, or many coordinate sets perhaps representing the trajectory of a molecular dynamics simulation. These coordinates can be examined using exam where the coordinates can be displayed in a molecular graphics program or the statistics for the structures can be reported. Supplementing exam are programs to analyze specific models such as xmd3 for reduced representation DNA models and xmr2 for reduced representation RNA models.

It is not unusual to take the structure from a simulation to start another round of simulations.

SEE ALSO

DIAGNOSTICS

Diagnostics are written to the standard error output. Diagnostics are prefixed with one to four sharp characters and the name of the program that produced the diagnostics. One sharp # indicates information, nothing to be concerned about. Two sharps ## indicate a warning, you need to correct the conditions that lead to the warning but the execution of the program was not compromised. Three sharps ### indicate a fatal error and usually the program is stopped. Four sharps #### indicate that a logic error that the programmer do not expect to occur has occurred anyway.

The diagnostics for two programs are documented in great detail. These are the diagnostics from the checking option in the descriptor convertor des and the diagnostics from the yammp shell interpreter in mimesis.

BUGS

Yammp is continuously being revised, corrected, expanded, etc. There is no guarantee that all the bugs have been removed.

NOTES

This site can be navigated via the hierarchical collection of links at the bottom of most pages. Immediately after the page are the links most closely related to this page, the manual pages. At the very bottom are links to other areas in YammpWeb.