Timestep

Files:	Timestep.h, Timestep.C
Derived from:	none
Global instance (if any):	none
Used in optional component:	Part of main VMD code

Description

The Timestep class is used to hold the dynamic data for a Molecule for a single step in a trajectory. It hold the coordinates, velocities, energies, etc. that vary with time. As each new Timestep is read in from some source (a file, or from a network connection) it is added to the animation list for the associated molecule; this list is maintained by the Animation object, from which each Molecule is derived.

Almost all the items in this class are public, so they may be retrieved quickly by other objects in VMD. This is not such a great design, however; see the notes below about future changes.

Constructors

• Timestep::Timestep(int n, float DT, float *newdata = NULL)
  The first argument is the number of objects (atoms) for which dynamic data will be stored. The second is the time which has elapsed between generation of this step a previous step (for example, for a molecular dynamics simulation, this would be the integration timestep). The final argument is the data to store in this step, if it has already been allocated. If not, new space will be allocated by Timestep.

Enumerations, lists or character name arrays

There are a number of globally defined macros in this class which are used as indices into the data arrays stored by this object. They are:

1. Energy Data Indices:
   • TSE_BOND - index to bond energy value.
   • TSE_ANGLE - index to angle energy value.
   • TSE_DIHE - index to dihedral energy value.
   • TSE_IMPR - index to improper dihedral energy value.
   • TSE_VDW - index to van der Waal energy value.
   • TSE_COUL - index to Coulomb energy value.
   • TSE_HBOND - index to hydrogen-bond energy value.
   • TSE_KE - index to total kinetic energy value.
   • TSE_PE - index to total potential energy value.
   • TSE_TOTAL - index to total energy value.
   • TSE_TEMP - index to temperature value.

2. Per-Atom Data Indices:
   • TSP_X - x coordinate.
   • TSP_Y - y coordinate.
   • TSP_Z - z coordinate.

3. Per-Patch Data Indices:
   • TSP_XLEN - length of patch in x direction.
   • TSP_YLEN - length of patch in y direction.
   • TSP_ZLEN - length of patch in z direction.
   • TSP_LOAD - computational load on the patch.
   • TSP_ATOMS - number of atoms in the patch.
   • TSP_NODE - node which contains the patch.

Internal data structures

• int needDataDelete - flag for whether we need to delete the storage space for the data array when this object is deleted.

• int num - number of atoms in this Timestep.

• float *pos - coordinates of all the atoms. This array has 3 * num elements, arranged as ([x1 y1 z1] [x2 y2 z2] ...).

• float *data - for each atom, there can be `extra' data, which Timestep does not not know the contents of. This is the data provided as the last argument in the constructor.

• float energy[] - energy values for this timestep. By default, they are zero unless they are explicitly changed by the creator of this timestep.

• int numPatches - the number of patches stored in this step. It may be zero (and definitely is zero for data which did not come from a network connection).

• float *patchData - data stored for each patch (the size, location, atoms per patch, etc.).

• float minpos[], maxpos[], mindata[], maxdata[], etc - the minimum and maximum values found in this Timestep for the various data quantities. Several parts of VMD need to know the range of data values some quantity takes in a Timestep.

• float COV[] - the x,y,z position of the center of volume.

• float scale_factor - the amount by which you would need to scale the coordinates in this step in order to fit them in a box in the range (-1 ... 1) in all dimensions.

• float dt - the time required to compute this timestep. If this is unknown, it is set to zero.

• int Initialized - has this been initialized? If so, then all the data items have been placed into the proper arrays, and the max and min values have been calculated.

Nonvirtual member functions

• float *create_patch_storage(int) - allocates internal storage to store data for the given number of patches. The number of patches is stored internally as well. Returns a pointer to the newly-allocated array.

• void init(void) - after all the data has been placed into a new Timestep instance, this routine calculate the max/min values for all the quantities, and anything else required based on atom coordinates, etc. Used for scaling and translating purposes.

Method of use

A new Timestep is created each time new coordinate data needs to be added to the end of the animation list. Use the following steps:

1. Create a new instance:
   Timestep *ts = new Timestep(atoms, dt);

2. Copy coordinate and energy data into the proper arrays, by accessing the public data items described above.

3. If there is patch data, first call create_patch_storage with the number of patches (to allocate storage), and then copy the patch data into the array which is returned by the function.

4. After all data is entered, the last step is to call the init routine. This goes through all the stored quantities (x, y, z position, atoms/patch, etc) and calculates the maximum and minimum values. It also finds the position of the center of volume, and the proper scaling factor.

Suggestions for future changes/additions

This could perhaps benefit from having a NameList store the different quantities, with a specific name associated with each quantity. Then, instead of having to hard-code into Timestep what data is being stored, you could just have a routine to add new items with a given name to the object, and other routines to access data by providing the proper name and index (or maybe just provide the name, and have returned the proper array storing the data).