force.h File Reference

Force evaluation library. More...

#include "mdapi/mdtypes.h"
#include "force/fparam.h"
#include "force/fdomain.h"
#include "force/fresult.h"
#include "force/fselect.h"
#include "force/defn.h"
#include "force/setup.h"
#include "force/compute.h"

Go to the source code of this file.

Defines
#define	FORCE_FAIL   (-1)
Typedefs
typedef Force_t	Force
Functions
Force *	force_create (ForceParam *fprm, ForceDomain *fdom, ForceSelect *fsel, const MD_Dvec initpos[])
	Constructor.
void	force_destroy (Force *)
	Destructor.
int	force_compute (Force *, ForceResult *fres, const MD_Dvec pos[])
	Perform force evaluation.
int	force_update_domain (Force *, ForceDomain *fdom)
	Update the simulation cell domain.
int	force_initialize (Force *, ForceParam *fprm, ForceDomain *fdom, ForceSelect *fsel, const MD_Dvec initpos[])
	Alternative constructor.
void	force_cleanup (Force *)
	Alternative destructor.
const MD_Dvec *	force_get_poswrap (const Force *)
	Return atomic coordinate offset array.
const MD_Dvec *	force_get_scaled_coords (const Force *)
	Return scaled atomic coordinate array.
int32 **	force_get_excl_list (const Force *)
	Return exclusion lists.
int32 **	force_get_scaled14_list (const Force *)
	Return scaled 1-4 exclusion lists.
double	force_get_volume (const Force *)
const MD_Dvec *	force_get_cell_center (const Force *)
const MD_Dvec *	force_get_cell_vectors (const Force *)
const double *	force_get_cell_lengths (const Force *)
const MD_Dvec *	force_get_row_transform (const Force *)
int32	force_get_cell_boundary (const Force *)
int32	force_get_domain_update (const Force *)
int	force_setup_scaled_minmax (Force *)
const MD_Dvec *	force_get_scaled_minmax (const Force *)
int	force_setup_lattice (Force *, int32 k1, int32 k2, int32 k3)
const MD_Dvec *	force_get_lattice_spacings (const Force *)

---

Detailed Description

Force evaluation library.

Author:

David J. Hardy

Date:

2004-2006

The Force_t class evaluates the basic force field for biomolecules. Boundary conditions may be nonperiodic or periodic (or semi-periodic) cells. There are four helper container classes: ForceParam_t to define the force field parameters, ForceDomain_t to define the cell geometry, ForceResult_t which holds the results of the force and energy computation, and the optional class ForceSelect_t which can be used to evaluate some subset of bonds or to compute interaction energies between two disjoint subsets of atoms.

The force evaluation can computes the following:

• bonds
• angles
• dihedrals
• impropers
• electrostatics - either direct all pairs or with a cutoff distance, with interaction potential either shifted (for smooth cutoff) or standard
• van der Waals - either direct all pairs or with a cutoff distance, with interaction potential either switched using the same switching function as used by NAMD 2.5 (for smooth cutoff) or standard
• boundary restraints - spherical and cylindrical restraints as computed by NAMD, intended for nonperiodic (or possibly semi-periodic) simulation

Other possiblities for computation of nonbonded interactions include:

• nonbonded exclusions - subtracts out excluded interactions (instead of accumulating the nonbonded pairs to be included) for either or both electrostatics and van der Waals. This can be used in conjunction with an externally called fast method for long range electrostatic interactions.
• full direct pairwise interactions - this is the approach; for periodic systems it uses nearest image convention. This is intended only for very small systems or for testing.

The Force_t class is used with four helper classes:

• ForceParam_t is configured at the beginning of the simulation to describe which aspects of the force field are to be evaluated, along with force field parameters and system topology data.
• ForceDomain_t defines the domain cell and boundary conditions.
• ForceResult_t provides containers for force and energy computation, providing buffer space for the accumulation of the different potential energies, atomic forces, and interaction energies.
• ForceSelect_t (optional) select for evaluation the energies from subsets of bonds or interaction energies and potentials between two disjoint subsets of atoms.

The atomic position coordinates for periodic simulation are maintained using an array of the true atomic positions that are permitted to be outside of the periodic cell. An array of offsets are maintained internally that, when added to the true position, give the corresponding position coordinates located within the cell. The array is recomputed with the assumption that any given position never changes more than the length of the ForceDomain_t cell vectors between calls to force_compute().

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, you can either turn off the computation of the electrostatics forces, or instead turn on the computation of electrostatics forces with the option to subtract out the nonbonded exclusions for electrostatics.

---

Define Documentation

#define FORCE_FAIL   (-1)

Return value from failed function call.

---

Function Documentation

void force_cleanup (  Force *   )

Alternative destructor. Use this to destroy a preallocated Force_t object. Frees any memory allocations during setup and resets object memory.

int force_compute (  Force *  , ForceResult *  fres, const MD_Dvec  pos[] )

Perform force evaluation. Parameters: [out]  fres  Receives force and potential results from computation. [in]  pos  Gives atomic position coordinates. Evaluate the force. This routine is to be called for each time step of a molecular dynamics simulation. The computed force and potential results are returned in the fres container. The provided pos coordinates do not have to be within the periodic cell, but it is assumed that they do not change more than the length of the ForceDomain_t cell vectors between subsequent calls. The position offsets that "wrap" the atomic coordinates back into the periodic cell are maintained internally. Returns: 0 for success or FORCE_FAIL on failure.

Force* force_create (  ForceParam *  fprm, ForceDomain *  fdom, ForceSelect *  fsel, const MD_Dvec  initpos[] )

Constructor. Parameters: [in]  fprm  Contains force field parameters and topology and describes which types of forces are to be evaluated. [in]  fdom  Defines domain cell and boundary conditions. [in]  fsel  (optional) Selects subsets of bonds and/or disjoint subsets of atoms for force and energy evaluation. [in]  initpos  Gives initial atomic position coordinates. Creates dynamically allocated Force_t force evaluation object and initializes it. Must call this routine first. The user should not change the fprm after calling this routine. Any changes to fdom should be immediately followed by a call to force_update_domain(). If no selections desired, then fsel can be set to NULL; otherwise, no changes should be made to fsel. This routine does not compute the force, however, it is assumed that the initial atomic position coordinates initpos will not change more than the length of the ForceDomain_t cell vectors between calling this routine and all subsequent calls to force_compute(). Returns: Pointer to Force_t object or NULL if memory allocation fails, if the fprm and objects are inconsistent, or if the fdom describes a periodic domain that is too small for the indicated cutoff distance.

void force_destroy (  Force *   )

Destructor. Frees memory allocations made internally during setup and destroys the dynamically allocated Force_t object. Call when finished using it.

int32** force_get_excl_list (  const Force *   )

Return exclusion lists. This returns the exclusion lists created during force_create(). 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.

const MD_Dvec* force_get_poswrap (  const Force *   )

Return atomic coordinate offset array. This returns an array of position offsets that "wrap" the atomic coordinates used in the most recent call to force_compute() (or force_create() ) back into the periodic cell.

int32** force_get_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_t::flags has indicated FORCE_EXCL_SCAL14.

int force_initialize (  Force *  , ForceParam *  fprm, ForceDomain *  fdom, ForceSelect *  fsel, const MD_Dvec  initpos[] )

Alternative constructor. Use this to construct a preallocated Force_t object. Initializes use of Force_t object, allocating memory as needed. Same notes apply as for force_create(). Returns: 0 for success or FORCE_FAIL on failure.

int force_update_domain (  Force *  , ForceDomain *  fdom )

Update the simulation cell domain. Parameters: [in]  fdom  Define a modified simulation cell domain dimensions. This needs to be called for changes to the initial ForceDomain_t fdom object provided to force_create(). Resets the transformation matrix and internal data storage needed for evaluation of nonbonded interactions. Returns: 0 for success or FORCE_FAIL if memory allocation fails or if fdom describes a periodic domain that is too small for the previously indicated cutoff distance.

---