force.h File Reference

Force evaluation library. More...

#include "mdapi/mdtypes.h"

Go to the source code of this file.

Classes
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...
Typedefs
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.
Enumerations
enum	ForceFlags_tag {   FORCE_BOND = 0x000001, FORCE_ANGLE = 0x000002, FORCE_DIHED = 0x000004, FORCE_IMPR = 0x000008,   FORCE_ELEC = 0x000010, FORCE_VDW = 0x000020, FORCE_BONDED = FORCE_BOND | FORCE_ANGLE | FORCE_DIHED | FORCE_IMPR, FORCE_NONBONDED = FORCE_ELEC | FORCE_VDW,   FORCE_ALL = FORCE_BONDED | FORCE_NONBONDED, FORCE_ELEC_DIRECT = 0x000040, FORCE_VDW_DIRECT = 0x000080, FORCE_DIRECT = FORCE_ELEC_DIRECT | FORCE_VDW_DIRECT,   FORCE_MASK_TYPE = 0x0000FF, FORCE_NONPERIODIC = 0x000000, FORCE_X_PERIODIC = 0x000100, FORCE_Y_PERIODIC = 0x000200,   FORCE_Z_PERIODIC = 0x000400, FORCE_PERIODIC = FORCE_X_PERIODIC | FORCE_Y_PERIODIC | FORCE_Z_PERIODIC, FORCE_MASK_PERIOD = 0x000F00, FORCE_SPHERE = 0x001000,   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,   FORCE_CONTINUOUS = FORCE_SMOOTH | FORCE_SWITCH, FORCE_ELEC_EXCL = 0x400000, FORCE_VDW_EXCL = 0x800000, FORCE_EXCL = FORCE_ELEC_EXCL | FORCE_VDW_EXCL,   FORCE_MASK_CUTOFF = 0xF00000, FORCE_MD_VACUUM = FORCE_ALL | FORCE_EXCL_SCAL14 | FORCE_CONTINUOUS, FORCE_MD_CELL = FORCE_MD_VACUUM | FORCE_PERIODIC }
	Flags to indicate which parts of the force field are to be evaluated. More...
enum	{ FORCE_FAIL = -1 }
Functions
int	force_init (Force *)
	Constructor.
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 *)
	Destructor.
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.

Author:

David J. Hardy

Date:

2003-2005

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:

• bonds
• angles
• dihedrals
• impropers
• electrostatics - uses a cutoff distance, either shifted or truncated
• van der Waals - uses cutoff and switching distances with the same switching function as used by NAMD 2.5
• boundary restraints - spherical and cylindrical restraints as computed by NAMD, intended for nonperiodic or semi-periodic systems
• nonbonded exclusions - subtracts out excluded interactions (instead of accumulating the nonbonded pairs to be included) for either or both electrostatics and van der Waals
• full direct electrostatics - this is the approach; for periodic systems it uses nearest image convention

The Force_tag class is used with three helper classes:

• ForceParam_tag is configured at the beginning of the simulation to describe which aspects of the force field are to be evaluated, along with force field parameter and molecule topology information
• ForceEnergy_tag returns the total potential energy along with parts of the potential energy (e.g. bond, angle, van der Waals)
• ForceResult_tag returns the total forces for each atom of the system and optionally the separated forces for each atom (e.g. bond, angle, van der Waals)

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:

• distance in Angstroms
• time in femtoseconds
• energy in kcal/mol
• force in kcal/mol/Angstrom

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

Caveats:

• Full electrostatics are not computed (at least not with a fast method). To use with an external electrostatics library: turn off the electrostatics capability. Instead you might want to turn on nonbonded exclusions for electrostatics.
• Periodic cells must be at least twice the length of the cutoff in each dimension. (This guideline seems preferable in practice.)
• Periodic cells must be orthogonal. Cell resizing requires reinitializing the Force_tag class, so this does not provide good support for constant pressure simulations.

---

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

Enumerator: 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: FORCE_ALL | FORCE_EXCL_SCAL14 | FORCE_ELEC_EXCL | FORCE_SWITCH 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. Enumerator: 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. Parameters: [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. Returns: 0 for success or FORCE_FAIL on failure.

void force_done (  Force *   )

Destructor. 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 *   )

Constructor. Initializes a Force_tag object. Must call this routine first. Returns: 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. Parameters: [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. Returns: 0 for success or FORCE_FAIL on failure.

---