Molecule objects

The objects used for displaying and rendering graphical objects in VMD are quite general, and can be used to draw essentially anything. The objects used by VMD to create, store, and manipulate molecules, which are illustrated in figure 3, are much more specific to the purpose of VMD, which is to visualize to dynamic properties of biopolymers (in particular proteins and nucleic acids). The heart of this category of object classes is the Molecule class, which is actually inherited from a number of base classes and for which several subclasses exist. MoleculeList is an object which maintains a list of all current molecules. There are also several helping objects which store data about particular components of each molecule.

Figure 3: Molecule objects used in VMD.

At the very top level of the Molecule hierarchy is the Animate class, which stores a list of Timestep objects. Nothing is known about the molecule at this level other than the number of atoms; a Timestep stores simply arrays of floating-point values for each of these atoms for each discrete timestep in the trajectory of the molecule. The Animate class also maintains the current frame in the trajectory, and the direction (i.e., fast-forward, reverse, pause) and speed of animation. The Timestep objects, one for each frame of animation in each molecule, are stored simply as pointers in a ResizeArray instance within the Animate object. A Timestep is currently quite simple, and stores data as publicly-available floating point arrays which are allocated when a new Timestep is created (or for some data which may be optionally stored for each step, by the users request). This is done primarily for speed since this data is accessed quite often. It may be helpful to improve this class in the future, by making a much more general method to store different types of atomic data for timesteps which would not require a change to the Timestep class each time. For example, the Timestep may just store a list of pointers to something like a TimeStepData class instance, where each TimeStepData would store some number of floating-point values.

At the next level, the BaseMolecule object is inherited from the Animate object. This object stores all the basic information which comprises the structure of the molecule. Data about the coordinates are stored by Animate, while BaseMolecule stores how the atoms are connected, what residues and segments exist, etc. When it is created, a BaseMolecule is empty, indicating no atoms or anything present. A virtual function int BaseMolecule::create() is used by BaseMolecule and all other class derived from BaseMolecule; this function is called when a new molecule is to be created, and derived classes do their creation tasks after which they call create for the parent class. BaseMolecule does NOT contain any data or functions for the drawing of the molecule, just for storing the structure. After a new molecule has been read in from some files or from a network connection, the structure of the molecule is analyzed and stored in a retrievable format. Several small classes help in this storage; they include the following:

• Atom
  This object stores the data for one atom in a molecule, including the name, segment, type, charge, mass, etc. A list of these Atom objects are stored in a BaseMolecule. Atoms are numbered 0 $\ldots$ N-1, where N is the number of atoms in the molecule; a pointer to the $n$th Atom object may be obtained through the routine Atom * BaseMolecule::atom(int n). Bonds are not stored as separate objects; instead, in each Atom object there is noted the number of bonds in which the Atom participates, and a list of the indices of the other atoms to which it is connected. Note that a bond is effectively stored twice (to speed rendering of the molecule), once for each atom which defines the bond.
• Residue
  Each residue such as an amino acid or nucleic acid is referenced by a single Residue object, which stores the indices of the corresponding atoms and information about how the residue is connected to other residues. A list of all the residues in a molecule is kept in the BaseMolecule class.
• Fragment
  A fragment is defined as a contiguous string of residues. This may be as short as one (i.e., a water molecule), or as long as an entire protein from N-terminus to C-terminus. A Fragment object stores a list of residues which form a fragment, noting their order and connectivity. A BaseMolecule stores a list of all the fragments which are found within the molecule.
• NameList
  A BaseMolecule also contains several lists of names which are basically NameList templates. They store the lists of unique names which occur in the molecule, i.e., the list of all atom names. These lists are maintained as public data member for speedy access by other parts of the program.

From BaseMolecule and from Displayable3D the DrawMolecule object is derived. This level of the Molecule hierarchy stores all the information about how to draw the molecule. A molecule in VMD is drawn as a composition of one or more representations of the molecule structure, which are contained within a DrawMolItem object (described later). A DrawMolecule stores a list of all the different representations (DrawMolItem) of the molecule that the user has selected, and contains routines to add, change, or delete these representations. Since it is also a Displayable, a DrawMolecule can specify its own display list, but currently all molecule drawing commands are contained within DrawMolItem objects.

A DrawMolItem is also derived from Displayable3D; its function is to maintain the display list with the proper drawing commands to render one specified representation of a molecule. When a new DrawMolItem is created, it is given the molecule for which it is to render an image, and instances of the following three objects which describe exactly what the representation is to be:

• AtomColor
  Stores the color index number which is to be used for each atom in the molecule when it is drawn; essentially, how to color the molecule. The coloring can be done in any number of ways, for example each residue a different color, or shaded through the color scale from the midpoint of the molecule outwards.
• AtomRep
  Stores what shape to draw the molecule as; essentially, how to draw the molecule. For example, bonds may be represented as thin lines, or solid cylinders, or not drawn at all.
• AtomSel
  Which atoms to draw. This objects takes as input a text string with an atom selection command, and determines from the string which atoms of the molecule the user wishes to have drawn.

An instance of all three of these objects, taken together as a group, completely define how a represenation of a molecule should be drawn, and so each DrawMolItem requires one of these objects to allow it to construct the list of drawing commands for the representation. Each DrawMolItem is a child Displayable of the parent DrawMolecule, and may be independently turned on or off. By doing it this way, a complex image of the molecule may be constructed by separate more basic components, which may be separately manipulated, while the set of components are kept with the same transformation (rotation, scaling, and centering) applied to the molecule as a whole.

The main base class Molecule is then derived from DrawMolecule. This is the level at which most other objects in VMD work with molecules, as pointers to instances of a Molecule class. In fact relatively little functionality is includes at this level. What this class does do, in fact, is provide the routines for reading in or writing out of animation frames from or to different coordinate file formats (i.e., PDB or DCD files). This is done through the use of a CoorFileData object, which encapsulates the information on how to read/write such a coordinate file (this includes storing which frames are to be read or written, the coordinate file format, and the current status of such an operation). Since Molecule is a subclass of Displayable, it has a prepare virtual routine which is called each time the Scene is to be drawn to the current DisplayDevice. Molecule uses this call to prepare to read/write a single coordinate set from/to the current coordinate file, if one is being processed. Thus, a coordinate file is not processed in one single operation, instead one frame is processed each time the Scene is drawn. This allows VMD to continue to animate and check for user commands while a coordinate file is being read or written. For the actual coordinate file reading or writing, the CoorFile base class and derived ICoorFile and OCoorFile classes abstract the action of taking a set of XYZ positions for a molecule and reading or writing a trajectory file. Specific versions of these classes for PDB and DCD files are used, and any other number of trajectory formats may be supported by developing new subclasses of ICoorFile and OCoorFile, with also an update to CoorFileData.

Up to the point just described are all the classes necessary to store and manipulate a molecule. However, there are several different ways for a molecule to be imported into VMD, and each method has a specific subclass of Molecule to provide the functions to read in the proper data and store it into the standard internal format of the Molecule class hierarchy. Currently, the following subclasses of Molecule exist:

• MoleculeFile
  Used to create a new molecule by reading structure information from a file, such as a PDB or PSF file. This object provides routines which understand the format of these data files, and which convert the data within the files to the internal molecular structure format used by BaseMolecule. This action is done when the create routine is called; after reading in the file and successfully creating the molecular structure, the create routine for Molecule is called, which then calls create for DrawMolecule, $\ldots$
• MoleculeRemote
  This reads a molecular structure directly from a molecular dynamics simulation program running as a separate process on the same or another computer. The data is transferred directly over the network, without using any intermediate files, using sockets (see section 3). Otherwise, it functions identically to MoleculeFile.

Thus, the steps in creating a new molecule in VMD are as follows:

1. Create a new empty Molecule object, by creating an instance of one of the subclasses in the list above and assigning it to a Molecule * variable. This new molecule is empty, with 0 atoms, 0 bonds, etc.
2. Give information to this new object on how the molecule is to be created. Much of this data is actually specified as arguments to the constructor of the special subclass used.
3. Call the function create for the new Molecule, which will do most of the work in creating the new molecule. During this process, the following actions are done:
   1. Data in the original format is read in from the proper source.
   2. Each atom is added one by one to the molecular structure via routines in BaseMolecule. The lists of unique names for molecule components are constructed during this process.
   3. After all atoms are read, the bonds between atoms are stored. With the atoms and namelists, this completely defines the basic structure of the molecule. This step may involve finding the bonds through a nearest-neighbor search (necessary when the structure is read from a PDB file).
   4. ``Extra'' data helpful in displaying the molecule is read, such as which atoms are hydrogen-bond donors or acceptors.
   5. After all data is read and the basic structure defined, the create routine in BaseMolecule analyzes the molecule and creates the lists of Residues, Fragments, and anything else which helps define the structure.
   6. An initial representation of the molecule is created by DrawMolecule, and the display list necessary to draw the molecule is constructed.
4. After it has been created, a request to read in any trajectory files is given to the new molecule if necessary.

The object which keeps track of all the currently-loaded Molecule objects is MoleculeList, of which there is exactly one in VMD assigned to the global variable moleculeList (although there is no reason why there could not be more than one). MoleculeList is an important object: it manages all the molecules, contains routines to allow an operation to be performed on a number of molecules at the same time, and supplies information on how the molecules are related to each other. MoleculeList is derived from Displayable as well: it is the top-level parent Displayable with all Molecule objects as child Displayables. Thus, turning off the MoleculeList turns off all the molecules, and similarly rotating or scaling the MoleculeList does so to all the molecules. There are no drawing commands currently for the MoleculeList itself (although they could be added for something which indicates relationships between the molecules). This is a useful trick in VMD: have a container class which is derived from Displayable, but which has no drawing commands of its own; instead, have it contain several child Displayable objects which form components of the complex object which is to be drawn. By applying rotations, translations, etc. to the container class, all the child components are similarly transformed, and they may be separately altered or turned on or off.