Main Page | Class List | Directories | File List | Class Members | File Members

force.h File Reference

Force evaluation library. More...

#include "mdapi/mdtypes.h"

Go to the source code of this file.


struct  ForceParam_tag
 Used to configure Force_tag class. More...
struct  ForceEnergy_tag
 Container class returning potential energies. More...
struct  ForceResult_tag
 Container class returning atomic forces. More...
struct  ForceCell_tag
 (For internal use only.) More...
struct  Force_tag
 Force evaluation class. More...


typedef ForceParam_tag ForceParam
 Used to configure Force_tag class.
typedef ForceEnergy_tag ForceEnergy
 Container class returning potential energies.
typedef ForceResult_tag ForceResult
 Container class returning atomic forces.
typedef ForceCell_tag ForceCell
 (For internal use only.)
typedef Force_tag Force
 Force evaluation class.


enum  ForceFlags_tag {
  FORCE_BOND = 0x000001, FORCE_ANGLE = 0x000002, FORCE_DIHED = 0x000004, FORCE_IMPR = 0x000008,
  FORCE_X_CYLINDER = 0x002000, FORCE_Y_CYLINDER = 0x004000, FORCE_Z_CYLINDER = 0x008000, FORCE_MASK_BC = 0x00F000,
  FORCE_EXCL_NONE = 0x000000, FORCE_EXCL_12 = 0x010000, FORCE_EXCL_13 = 0x020000, FORCE_EXCL_14 = 0x030000,
  FORCE_EXCL_SCAL14 = 0x040000, FORCE_MASK_EXCL = 0x0F0000, FORCE_SMOOTH = 0x100000, FORCE_SWITCH = 0x200000,
 Flags to indicate which parts of the force field are to be evaluated. More...
enum  { FORCE_FAIL = -1 }


int force_init (Force *)
int force_setup (Force *, ForceParam *fp, ForceEnergy *fe, ForceResult *fr)
 Setup the Force_tag object.
int force_compute (Force *, const MD_Dvec *pos, MD_Dvec *wrap)
 Perform force evaluation.
void force_done (Force *)
int32 ** force_excl_list (const Force *)
 Return exclusion lists.
int32 ** force_scaled14_list (const Force *)
 Return scaled 1-4 exclusion lists.
int force_setup_bonded (Force *)
int force_setup_nonbonded (Force *)
int force_setup_nonbonded_cells (Force *)
int force_setup_boundary (Force *)
int force_compute_bonded (Force *, const MD_Dvec *pos)
int force_compute_nonbonded (Force *, const MD_Dvec *pos, MD_Dvec *wrap)
int force_compute_boundary (Force *, const MD_Dvec *pos, const MD_Dvec *wrap)

Detailed Description

Force evaluation library.

David J. Hardy
The Force_tag class evaluates the basic force field for biomolecules. Boundary conditions may be nonperiodic or orthogonal periodic (or semi-periodic) cells. Nonbonded interactions are treated using a cutoff distance. Helper class ForceParam_tag is used for initialization. Two helper classes ForceEnergy_tag and ForceResult_tag provide computed energies and forces, respectively.

The force evaluation can compute subsets from the following:

The Force_tag class is used with three helper classes: Periodic boundaries are computed using an array of the true atomic positions with an array of the wrapped offset optionally returned, so that the atom position that lies within the cell (see force_compute() below) is always:
   pos[i] + wrap[i]

The units are as outlined by the MDAPI documentation:

The internals of the force field parameter data types and topology data types are discussed in detail by the MDAPI documentation.


Typedef Documentation

typedef struct Force_tag Force

Force evaluation class.

Members should be treated as private.

typedef struct ForceEnergy_tag ForceEnergy

Container class returning potential energies.

User-supplied container class that returns potential energies from force_compute() routine. It is convenient to separate the energy data from the force results. Each respective value is meaningful only if the ForceParam_tag::flags has indicated that potential be evaluated.

typedef struct ForceParam_tag ForceParam

Used to configure Force_tag class.

User sets the internal fields of this class in order to configure the evaluation performed by the Force_tag class. The ForceParam_tag class is intended to be setup once and used to initialize the Force_tag class.

The user provides and retains ownership of memory buffer space for all arrays. The force field parameter and topology arrays all follow the MDAPI guidelines as defined by mdtypes.h file. In particular, it is expected that the proper cross-indexing between topology and force field parameter arrays have been established. The best way to do this is to use the MDIO library for reading the relevant force field parameter and topology files.

The parameter atom_len indicates the number of atoms in the system, providing the expected array length of the ForceResult_tag arrays and the pos and wrap arrays passed to force_compute().

The boundary restraint and nonbonded parameters follow the NAMD conventions, as described in its documentation.

The flags indicates what parts of the force field are to be evaluated. It is assigned a bitwise ORed collection of ForceFlags_tag constants.

typedef struct ForceResult_tag ForceResult

Container class returning atomic forces.

User-supplied container class that returns atomic forces from force_compute() routine. It is convenient to separate the force results from the energy data. The arrays (if defined) must have enough buffer space for ForceParam_tag::atom_len atoms. The caller must perform memory management for these array buffers.

The ForceResult_tag::f array must be supplied. All of the others are optional. If a pointer is not NULL and the ForceParam_tag::flags has indicated the evaluation of that corresponding force type, then that array is expected to have space for ForceParam_tag::atom_len atoms and will receive those partial force contributions during the call to force_compute().

Enumeration Type Documentation

anonymous enum

FORCE_FAIL  Return value from failed function call.

enum ForceFlags_tag

Flags to indicate which parts of the force field are to be evaluated.

Flags should be bitwise ORed together, used to initialize ForceParam_tag::flags field.

There are some values that collect commonly used flags:

  • FORCE_MD_VACUUM is good for nonperiodic systems without boundary restraints (you can OR in desired restraints flag).
  • FORCE_MD_CELL is good for fully periodic systems.
These both perform continuous cutoff nonbonded evaluations using scaled 1-4 exclusion policy.

If you want to use an external electrostatic library, you can use the Force_tag class to subtract out electrostatic exclusions by defining the following flags:

to compute all bonded interactions and smoothly switched van der Waals interactions using the scaled 1-4 exclusion policy; you can also include with this flags to define periodic boundary conditions or nonperiodic boundary restraints.
FORCE_BOND  Evaluate bond interactions.
FORCE_ANGLE  Evaluate angle interactions.
FORCE_DIHED  Evaluate dihedral interactions.
FORCE_IMPR  Evaluate improper interactions.
FORCE_ELEC  Evaluate electrostatic interactions.
FORCE_VDW  Evaluate van der Waals interactions.
FORCE_BONDED  Collection of flags: evaluate all types of bonded interactions.
FORCE_NONBONDED  Collection of flags: evaluate all types of nonbonded interactions.
FORCE_ALL  Collection of flags: evaluate all types of bonded and nonbonded interactions.
FORCE_ELEC_DIRECT  Perform direct evaluation of electrostatic interactions.
FORCE_VDW_DIRECT  Perform direct evaluation of van der Waals interactions.
FORCE_DIRECT  Collection of flags: perform direct evaluation of all nonbonded interactions.
FORCE_MASK_TYPE  (internal use only)
FORCE_NONPERIODIC  Indicates nonperiodic system.
FORCE_X_PERIODIC  Indicates periodicity in x-direction.
FORCE_Y_PERIODIC  Indicates periodicity in y-direction.
FORCE_Z_PERIODIC  Indicates periodicity in z-direction.
FORCE_PERIODIC  Collection of flags: indicates fully periodic system.
FORCE_MASK_PERIOD  (internal use only)
FORCE_SPHERE  Use spherical boundary restraints.
FORCE_X_CYLINDER  Use cylindrical boundary restraints with axis aligned in x-direction.
FORCE_Y_CYLINDER  Use cylindrical boundary restraints with axis aligned in y-direction.
FORCE_Z_CYLINDER  Use cylindrical boundary restraints with axis aligned in z-direction.
FORCE_MASK_BC  (internal use only)
FORCE_EXCL_NONE  Do not exclude any nonbonded pairs except for those indicated explicitly within the ForceParam_tag::excl array.
FORCE_EXCL_12  Exclude 1-2 interactions (atoms joined by spring bond).
FORCE_EXCL_13  Exclude 1-3 interactions (atoms joined by pair of spring bonds), which includes all angles.
FORCE_EXCL_14  Exclude 1-4 interactions (atoms joined by trio of spring bonds), which includes all dihedrals and impropers.
FORCE_EXCL_SCAL14  Exclude 1-3 interactions but redefine 1-4 interactions using alternate van der Waals parameters and electrostatic 1-4 scaling constant. (This is the commonly used standard for modern systems.)
FORCE_MASK_EXCL  (internal use only)
FORCE_SMOOTH  Apply shifting to electrostatics potential so that cutoff interactions are smooth.
FORCE_SWITCH  Apply switching function, piecewise defined from cutoff to switching distance, to van der Waals potential so that cutoff interactions are smooth.
FORCE_CONTINUOUS  Collection of flags: apply electrostatic smoothing and van der Waals switching.
FORCE_ELEC_EXCL  Do not evaluate electrostatic interactions. Instead subtract out nonbonded exclusions for electrostatics.
FORCE_VDW_EXCL  Do not evaluate van der Waals interactions. Instead subtract out nonbonded exclusions for van der Waals.
FORCE_EXCL  Collection of flags: subtract out both electrostatics and van der Waals exclusions.
FORCE_MASK_CUTOFF  (internal use only)
FORCE_MD_VACUUM  Collection of flags: good default for cutoff MD in a vacuum, scaled 1-4 exclusion policy, no boundary restraints.
FORCE_MD_CELL  Collection of flags: good default for cutoff MD with periodic boundaries, scaled 1-4 exclusion policy.

Function Documentation

int force_compute Force ,
const MD_Dvec *  pos,
MD_Dvec *  wrap

Perform force evaluation.

[in] pos The atomic positions supplied by user.
[in,out] wrap Updated offset data needed to wrap the actual atomic position back to its "periodic image" into the periodic cell.
Evaluate the force. This routine is to be called for each time step of a molecular dynamics simulation.

The convention here is that pos[i] changes "smoothly" during simulation, perhaps wandering outside the periodic cell, with the atomic coordinate pos[i]+wrap[i] always mapping back into the cell. The wrap array is optional, but if supplied it is expected to be of length ForceParam_tag::atom_len, and it should either be initialized to all zeros or the result of some previous call to force_compute(). The wrap array is unused for nonperiodic systems.

0 for success or FORCE_FAIL on failure.

void force_done Force  ) 


Frees memory allocations made internally during force_setup(). Call when finished using Force_tag object.

int32** force_excl_list const Force  ) 

Return exclusion lists.

This returns the exclusion lists created during force_setup(). The format is a jagged array of arrays. The first array is indexed for each atom, and the second array is an ordered list of atom numbers indicating which pairs are to be excluded. Each of these second arrays ends with a sentinel value greater than or equal to the number of atoms. The atom numbering is C-style beginning with 0.

int force_init Force  ) 


Initializes a Force_tag object. Must call this routine first.

0 for success or FORCE_FAIL on failure.

int32** force_scaled14_list const Force  ) 

Return scaled 1-4 exclusion lists.

The same format as returned by force_excl_list(), except that this represents only the atomic pairs participating in scaled 1-4 interactions. This list is not meaningful unless the ForceParam_tag::flags has indicated FORCE_EXCL_SCAL14.

int force_setup Force ,
ForceParam fp,
ForceEnergy fe,
ForceResult fr

Setup the Force_tag object.

[in] fp The ForceParam_tag object used for configuration.
[in] fe The ForceEnergy_tag container into which energies will be returned.
[in] fr The ForceResult_tag container into which atomic forces will be returned.
Must call this routine once before force_compute(). The user should not change these objects, particularly not the ForceParam_tag object, after calling this routine.

0 for success or FORCE_FAIL on failure.

Generated on Mon Sep 26 10:55:19 2005 for MDX by  doxygen 1.4.4