step.h File Reference

Time stepping library. More...

#include "mdapi/mdtypes.h"

Go to the source code of this file.

Classes
struct	StepParam_t
	Parameters for configuring Step class. More...
struct	StepSystem_t
	Provides system data through callback. More...
Typedefs
typedef enum StepMethod_t	StepMethod
	Available methods.
typedef enum StepOption_t	StepOption
	Available options.
typedef StepSystem_t	StepSystem
typedef StepParam_t	StepParam
	Parameters for configuring Step class.
typedef Step_t	Step
Enumerations
enum	{ STEP_FAILURE = -1, STEP_SUCCESS = 0 }
	Constant values. More...
enum	StepMethod_t {   STEP_VERLET = 1, STEP_SHADOW, STEP_TEMPBATH, STEP_NHEXP,   STEP_DRUDE_NH, STEP_DRUDE_ROUX, STEP_DRUDE_CHEN, STEP_CGMIN,   STEP_METHOD_MARKER }
	Available methods. More...
enum	StepOption_t {   STEP_INITVEL = 0x001, STEP_RESTARTVEL = 0x002, STEP_REMOVECOM = 0x004, STEP_ZEROLINMO = 0x008,   STEP_SETTLE = 0x010, STEP_VIRIAL = 0x020, STEP_MOMENTUM = 0x040, STEP_FIXEDATOMS = 0x080,   STEP_CONSTRAINTS = 0x100, STEP_OPTION_MARKER = 0x1FF }
	Available options. More...
enum	StepShadowIndex_t {   STEP_SHADOW_4 = 0, STEP_SHADOW_8, STEP_SHADOW_12, STEP_SHADOW_16,   STEP_SHADOW_20, STEP_SHADOW_24, STEP_SHADOW_MAXINDEX }
	For indexing StepSystem_t::shadow_energy. More...
Functions
Step *	new_Step (void)
	Constructor.
void	delete_Step (Step *)
	Destructor.
int	step_setup (Step *, StepParam *param, MD_Dvec *pos, MD_Dvec *vel, MD_Dvec *force)
	Setup.
int	step_compute (Step *, int32 numsteps)
	Performs the time stepping.
const char *	step_errmsg (Step *)
	Error message.
void	step_cleanup (Step *)
	Cleanup.

---

Detailed Description

Time stepping library.

Author:

David J. Hardy

Date:

2005

The Step_t class performs time integration or energy minimization of a system of atoms. Choose between various methods:

• velocity-Verlet (NVE)
• shadow Hamiltonian (NVE)
• weakly coupled temperature bath
• Nose-Hoover thermostat (NVT)
• Drude oscillators with dual thermostating (NVT,T*)
• energy minimization using conjugate gradient search

and various options:

• assign initial velocities from initial temperature distribution
• remove center of mass motion from initial velocity assignment
• zero linear momentum
• rigid waters

The StepParam_t structure is setup by the caller to configure the Step_t class. Three callback functions are required: one providing force evaluation to Step_t for given positions, one collecting data from Step_t at the end of a step, and one receiving text output.

The data collection callback receives a StepSystem_t structure that contains (among other things) current positions, velocities, and energy reductions.

The units are as outlined by the MDAPI documentation:

• distance in Angstroms
• time in femtoseconds
• velocity in Angstroms/femtosecond
• energy in kcal/mol
• force in kcal/mol/Angstrom
• temperature in degrees Kelvin

---

Typedef Documentation

typedef struct StepParam_t StepParam

Parameters for configuring Step class. User must provide values where appropriate, depending on selected method. Must provide callbacks. Retains ownership of topology and force field arrays.

---

Enumeration Type Documentation

anonymous enum

Constant values. Enumeration values: STEP_FAILURE  Return value indicating an error occurred. STEP_SUCCESS  Return value indicating all is well.

enum StepMethod_t

Available methods. Enumeration values: STEP_VERLET  velocity Verlet STEP_SHADOW  computes high-order approximations to the shadow Hamiltonian STEP_TEMPBATH  weak coupling to a temperature bath (Berendsen, et al., 1984) STEP_NHEXP  Nose-Hoover thermostat with explicit steps STEP_DRUDE_NH  thermalized Drude oscillators using dual Nose-Hoover thermostats STEP_DRUDE_ROUX  thermalized Drude oscillators using Roux's Nose-Hoover integrator STEP_DRUDE_CHEN  thermalized Drude oscillators using Chen's method STEP_CGMIN  energy minimization using conjugate gradient search directions

enum StepOption_t

Available options. Enumeration values: STEP_INITVEL  assign random velocities from initial temperature distribution STEP_RESTARTVEL  restarting from velocity file, i.e. prevent STEP_REMOVECOM from modifying the velocities STEP_REMOVECOM  remove center of mass motion of velocities assigned from an initial temperature distribution, and decrease ndegfreedom by 3 (do not modify velocities if STEP_RESTARTVEL is set) STEP_ZEROLINMO  impose holonomic constraint to keep linear momentum zero; should be used to correct for PME or MSM approximations only when linear momentum would otherwise be conserved STEP_SETTLE  use SETTLE (analytical RATTLE) for rigid water STEP_VIRIAL  compute kinetic contribution to virial STEP_MOMENTUM  compute linear and angular momentum STEP_FIXEDATOMS  pay attention to fixed atom status flag; fixed atoms are assigned zero velocity, their positions are left unchanged, and the number of fixed atoms is considered in determining number of degrees of freedom STEP_CONSTRAINTS  harmonic constraints/restraints are to be applied to some atoms in the system

enum StepShadowIndex_t

For indexing StepSystem_t::shadow_energy. Enumeration values: STEP_SHADOW_4  4th order approximation STEP_SHADOW_8  8th order approximation STEP_SHADOW_12  12th order approximation STEP_SHADOW_16  16th order approximation STEP_SHADOW_20  20th order approximation STEP_SHADOW_24  24th order approximation

---

Function Documentation

void step_cleanup (  Step *   )

Cleanup. Call this to clean up internal state of Step_t object.

int step_compute (  Step *  , int32  numsteps )

Performs the time stepping. Parameters: [in]  numsteps  Number of steps to integrate or minimize the system. Note that calls back to the StepParam_t::compute_force() routine account for the majority of the computational cost. Returns: STEP_SUCCESS, or STEP_FAILURE on error.

const char* step_errmsg (  Step *   )

Error message. Provide text error message; call if an error is returned by another Step_t class method.

int step_setup (  Step *  , StepParam *  param, MD_Dvec *  pos, MD_Dvec *  vel, MD_Dvec *  force )

Setup. Parameters: [in]  param  StepParam_t object for configuration. [in,out]  pos  Initial positions. [in,out]  vel  Initial velocities. [in,out]  force  Array buffer for forces. Initializes the Step_t object. Must be called before Step_t::step_compute(). Initial positions must be provided. The other two arrays can be optionally assigned NULL. (If vel is not provided, then the initial velocities are assigned from the initial temperature distribution indicated in StepParam_t, no matter the value of StepParam_t::option.) Caller is responsible for memory management for any provided arrays. Returns: STEP_SUCCESS, or STEP_FAILURE on error.

---