Main Page | Namespace List | Class Hierarchy | Alphabetical List | Class List | File List | Class Members | File Members

colvar::cvc Class Reference

Colvar component (base class); most implementations of utilize one or more or objects to access atoms. More...

#include <colvarcomp.h>

Inheritance diagram for colvar::cvc:

colvarparse colvar::alpha_angles colvar::alpha_dihedrals colvar::angle colvar::dihedral colvar::distance colvar::distance_z colvar::eigenvector colvar::gyration colvar::h_bond colvar::orientation List of all members.

Public Member Functions

colvarvalue::Type type () const
 Type of that this cvc provides.
 cvc (std::string const &conf)
 Constructor.
void parse_group (std::string const &conf, char const *group_key, cvm::atom_group &group, bool optional=false)
 Within the constructor, make a group parse its own options from the provided configuration string.
 cvc ()
 Default constructor (used when objects are declared within other ones).
virtual ~cvc ()
 Destructor.
colvarvalue fdiff_change (cvm::atom_group &group)
 When b_debug_gradients is true, this function can be used to calculate the estimated change in the value using the change in the atomic coordinates times the atomic gradients.
virtual void calc_value ()=0
 Calculate the variable.
virtual void calc_gradients ()=0
 Calculate the atomic gradients, to be reused later in order to apply forces.
virtual void calc_force_invgrads ()
 Calculate the total force from the system using the inverse atomic gradients.
virtual void calc_Jacobian_derivative ()
 Calculate the divergence of the inverse atomic gradients.
virtual colvarvalue value () const
 Return the previously calculated value.
virtual colvarvalue system_force () const
 Return the previously calculated system force.
virtual colvarvalue Jacobian_derivative () const
 Return the previously calculated divergence of the inverse atomic gradients.
virtual void apply_force (colvarvalue const &cvforce)=0
 Apply the collective variable force, by communicating the atomic forces to the simulation program (Note: the member is not altered by this function).
virtual cvm::real dist2 (colvarvalue const &x1, colvarvalue const &x2) const
 Square distance between x1 and x2 (can be redefined to transparently implement constraints, symmetries and periodicities).
virtual colvarvalue dist2_lgrad (colvarvalue const &x1, colvarvalue const &x2) const
 Gradient (with respect to x1) of the square distance (can be redefined to transparently implement constraints, symmetries and periodicities).
virtual colvarvalue dist2_rgrad (colvarvalue const &x1, colvarvalue const &x2) const
 Gradient (with respect to x2) of the square distance (can be redefined to transparently implement constraints, symmetries and periodicities).
virtual cvm::real compare (colvarvalue const &x1, colvarvalue const &x2) const
 Return a positive number if x2>x1, zero if x2==x1, negative otherwise (can be redefined to transparently implement constraints, symmetries and periodicities) Note: it only works with scalar variables, otherwise raises an error.

Public Attributes

std::string name
 The name of the object (helps to identify this cvc instance when debugging).
std::string function_type
 Description of the type of collective variable.
cvm::real sup_coeff
 Coefficient in the polynomial superposition (default: 1.0).
int sup_np
 Exponent in the polynomial superposition (default: 1).
cvm::real period
 Period of this cvc value, (default: 0.0, non periodic).
bool b_periodic
bool b_debug_gradients
 If true, calc_gradients() will calculate finite-difference gradients alongside the analytical ones and report their differences.
bool b_inverse_gradients
 If this flag is false (default), inverse gradients (derivatives of atom coordinates with respect to x) are unavailable; it should be set to true by the constructor of each derived object capable of calculating them.
bool b_Jacobian_derivative
 If this flag is false (default), the Jacobian derivative (divergence of the inverse gradients) is unavailable; it should be set to true by the constructor of each derived object capable of calculating it.

Protected Attributes

colvarvalue x
 Cached value.
colvarvalue x_old
 Value at the previous step.
colvarvalue ft
 Calculated system force (Note: this is calculated from the total atomic forces read from the program, subtracting fromt the "internal" forces of the system the "external" forces from the colvar biases).
colvarvalue jd
 Calculated Jacobian derivative (divergence of the inverse gradients): serves to calculate the phase space correction.

Detailed Description

Colvar component (base class); most implementations of utilize one or more or objects to access atoms.

A object (or an object of a cvc-derived class) specifies how to calculate a collective variable, its gradients and other related physical quantities which do not depend only on the numeric value (the class already serves this purpose).

No restriction is set to what kind of calculation a object performs (usually calculate an analytical function of atomic coordinates). The only constraint is that the value calculated is implemented as a object. This serves to provide a unique way to calculate scalar and non-scalar collective variables, and specify if and how they can be combined together by the parent object.

If you wish to implement a new collective variable component, you should write your own class by inheriting directly from , or one of its derived classes (for instance, is frequently used, because it provides useful data and function members for any colvar based on two atom groups). The steps are:

1. add the name of this class under colvar.h
2. add a call to the parser in colvar.C, within the function colvar::colvar()
3. declare the class in colvarcomp.h
4. implement the class in one of the files colvarcomp_*.C
 The cvm::atom and cvm::atom_group classes are available to transparently communicate with the simulation program. However, they are not strictly needed, as long as all the degrees of freedom associated to the cvc are properly evolved by a simple call to e.g. apply_force().

Definition at line 51 of file colvarcomp.h.

Constructor & Destructor Documentation

colvar::cvc::cvc (  std::string const &  conf  ) 
 

Constructor.

At least one constructor which reads a string should be defined for every class inheriting from cvc

Parameters:
conf Contents of the configuration file pertaining to this

Definition at line 17 of file colvarcomp.C.

References b_debug_gradients, colvar::b_inverse_gradients, colvar::b_periodic, colvarmodule::debug(), colvarmodule::log(), period, sup_coeff, and sup_np.

00018   : sup_coeff (1.0), sup_np (1),
00019     b_periodic (false),
00020     b_debug_gradients (false),
00021     b_inverse_gradients (false),
00022     b_Jacobian_derivative (false)
00023 {
00024   if (cvm::debug())
00025     cvm::log ("Initializing cvc base object.\n");
00026 
00027   get_keyval (conf, "name", this->name, std::string (""), parse_silent);
00028 
00029   get_keyval (conf, "componentCoeff", sup_coeff, 1.0);
00030   get_keyval (conf, "componentExp", sup_np, 1);
00031 
00032   get_keyval (conf, "period", period, 0.0, parse_silent);
00033 
00034   get_keyval (conf, "debugGradients", b_debug_gradients, false, parse_silent);
00035 
00036   if (cvm::debug())
00037     cvm::log ("Done initializing cvc base object.\n");
00038 }

colvar::cvc::cvc (   ) 
 

Default constructor (used when objects are declared within other ones).

Definition at line 8 of file colvarcomp.C.

00009   : sup_coeff (1.0), sup_np (1),
00010     b_periodic (false),
00011     b_debug_gradients (false),
00012     b_inverse_gradients (false),
00013     b_Jacobian_derivative (false)
00014 {}

colvar::cvc::~cvc (   )  [virtual]
 

Destructor.

Definition at line 57 of file colvarcomp.C.

00058 {}

Member Function Documentation

virtual void colvar::cvc::apply_force (  colvarvalue const &  cvforce  )  [pure virtual]
 

Apply the collective variable force, by communicating the atomic forces to the simulation program (Note: the member is not altered by this function).

Note: multiple calls to this function within the same simulation step will add the forces altogether

Parameters:
cvforce The collective variable force, usually coming from the biases and eventually manipulated by the parent object

Implemented in colvar::distance, colvar::distance_dir, colvar::distance_z, colvar::distance_xy, colvar::min_distance, colvar::gyration, colvar::eigenvector, colvar::angle, colvar::dihedral, colvar::coordnum, colvar::h_bond, colvar::alpha_dihedrals, colvar::alpha_angles, colvar::orientation, colvar::orientation_angle, colvar::rmsd, and colvar::logmsd.

void colvar::cvc::calc_force_invgrads (   )  [virtual]
 

Calculate the total force from the system using the inverse atomic gradients.

Reimplemented in colvar::distance, colvar::distance_z, colvar::distance_xy, colvar::gyration, colvar::eigenvector, colvar::dihedral, colvar::rmsd, and colvar::logmsd.

Definition at line 61 of file colvarcomp.C.

References colvarmodule::fatal_error(), and function_type.

00062 {
00063   cvm::fatal_error ("Error: calculation of inverse gradients is not implemented "
00064                     "for colvar components of type \""+function_type+"\".\n");
00065 }

virtual void colvar::cvc::calc_gradients (   )  [pure virtual]
 

Calculate the atomic gradients, to be reused later in order to apply forces.

Implemented in colvar::distance, colvar::distance_dir, colvar::distance_z, colvar::distance_xy, colvar::min_distance, colvar::gyration, colvar::eigenvector, colvar::angle, colvar::dihedral, colvar::coordnum, colvar::h_bond, colvar::alpha_dihedrals, colvar::alpha_angles, colvar::orientation, colvar::orientation_angle, colvar::rmsd, and colvar::logmsd.

void colvar::cvc::calc_Jacobian_derivative (   )  [virtual]
 

Calculate the divergence of the inverse atomic gradients.

Reimplemented in colvar::distance, colvar::distance_z, colvar::distance_xy, colvar::gyration, colvar::eigenvector, colvar::dihedral, colvar::rmsd, and colvar::logmsd.

Definition at line 68 of file colvarcomp.C.

References colvarmodule::fatal_error(), and function_type.

00069 {
00070   cvm::fatal_error ("Error: calculation of inverse gradients is not implemented "
00071                     "for colvar components of type \""+function_type+"\".\n");
00072 }

virtual void colvar::cvc::calc_value (   )  [pure virtual]
 

Calculate the variable.

Implemented in colvar::distance, colvar::distance_dir, colvar::distance_z, colvar::distance_xy, colvar::min_distance, colvar::gyration, colvar::eigenvector, colvar::angle, colvar::dihedral, colvar::coordnum, colvar::h_bond, colvar::alpha_dihedrals, colvar::alpha_angles, colvar::orientation, colvar::orientation_angle, colvar::rmsd, and colvar::logmsd.

cvm::real colvar::cvc::compare (  colvarvalue const &  x1,
colvarvalue const &  x2
)  const [inline, virtual]
 

Return a positive number if x2>x1, zero if x2==x1, negative otherwise (can be redefined to transparently implement constraints, symmetries and periodicities) Note: it only works with scalar variables, otherwise raises an error.

Reimplemented in colvar::distance, colvar::distance_z, colvar::distance_xy, colvar::min_distance, colvar::gyration, colvar::eigenvector, colvar::angle, colvar::dihedral, colvar::coordnum, colvar::h_bond, colvar::alpha_dihedrals, colvar::alpha_angles, colvar::orientation, colvar::orientation_angle, colvar::rmsd, and colvar::logmsd.

Definition at line 276 of file colvarcomp.h.

References colvarmodule::fatal_error(), colvarmodule::real, and type().

00278 {
00279   if (this->type() == colvarvalue::type_scalar) {
00280     return cvm::real (x1 - x2);
00281   } else {
00282     cvm::fatal_error ("Error: you requested an operation which requires "
00283                       "comparison between two non-scalar values.\n");
00284     return 0.0;
00285   }
00286 }

cvm::real colvar::cvc::dist2 (  colvarvalue const &  x1,
colvarvalue const &  x2
)  const [inline, virtual]
 

Square distance between x1 and x2 (can be redefined to transparently implement constraints, symmetries and periodicities).

colvar::cvc::dist2() and the related functions are declared as "const" functions, but not "static", because additional parameters defining the metrics (e.g. the periodicity) may be specific to each colvar::cvc object.

If symmetries or periodicities are present, the colvar::cvc::dist2() should be redefined to return the "closest distance" value and colvar::cvc::dist2_lgrad(), colvar::cvc::dist2_rgrad() to return its gradients.

If constraints are present (and not already implemented by any of the types), the colvar::cvc::dist2_lgrad() and colvar::cvc::dist2_rgrad() functions should be redefined to provide a gradient which is compatible with the constraint, i.e. already deprived of its component normal to the constraint hypersurface.

Finally, another useful application, if you are performing very many operations with these functions, could be to override the member functions and access directly its member data. For instance: to define dist2(x1,x2) as (x2.real_value-x1.real_value)*(x2.real_value-x1.real_value) in case of a scalar type.

Reimplemented in colvar::distance, colvar::distance_z, colvar::distance_xy, colvar::min_distance, colvar::gyration, colvar::eigenvector, colvar::angle, colvar::dihedral, colvar::coordnum, colvar::h_bond, colvar::alpha_dihedrals, colvar::alpha_angles, colvar::orientation, colvar::orientation_angle, colvar::rmsd, and colvar::logmsd.

Definition at line 258 of file colvarcomp.h.

References colvarvalue::dist2().

00260 {
00261   return x1.dist2 (x2);
00262 }

colvarvalue colvar::cvc::dist2_lgrad (  colvarvalue const &  x1,
colvarvalue const &  x2
)  const [inline, virtual]
 

Gradient (with respect to x1) of the square distance (can be redefined to transparently implement constraints, symmetries and periodicities).

Reimplemented in colvar::distance, colvar::distance_z, colvar::distance_xy, colvar::min_distance, colvar::gyration, colvar::eigenvector, colvar::angle, colvar::dihedral, colvar::coordnum, colvar::h_bond, colvar::alpha_dihedrals, colvar::alpha_angles, colvar::orientation, colvar::orientation_angle, colvar::rmsd, and colvar::logmsd.

Definition at line 264 of file colvarcomp.h.

References colvarvalue::dist2_grad().

00266 {
00267   return x1.dist2_grad (x2);
00268 }

colvarvalue colvar::cvc::dist2_rgrad (  colvarvalue const &  x1,
colvarvalue const &  x2
)  const [inline, virtual]
 

Gradient (with respect to x2) of the square distance (can be redefined to transparently implement constraints, symmetries and periodicities).

Reimplemented in colvar::distance, colvar::distance_z, colvar::distance_xy, colvar::min_distance, colvar::gyration, colvar::eigenvector, colvar::angle, colvar::dihedral, colvar::coordnum, colvar::h_bond, colvar::alpha_dihedrals, colvar::alpha_angles, colvar::orientation, colvar::orientation_angle, colvar::rmsd, and colvar::logmsd.

Definition at line 270 of file colvarcomp.h.

References colvarvalue::dist2_grad().

00272 {
00273   return x2.dist2_grad (x1);
00274 }

colvarvalue colvar::cvc::fdiff_change (  cvm::atom_group &  group  ) 
 

When b_debug_gradients is true, this function can be used to calculate the estimated change in the value using the change in the atomic coordinates times the atomic gradients.

Definition at line 75 of file colvarcomp.C.

References colvarmodule::atom_group::old_pos, colvarmodule::atom_group::positions(), colvarvalue::type(), and x.

00076 {  
00077   colvarvalue change (x.type());
00078 
00079   if (group.old_pos.size()) {
00080     for (size_t i = 0; i < group.size(); i++) {
00081       cvm::rvector const &pold = group.old_pos[i];
00082       cvm::rvector const &p = group[i].pos;
00083       change += group[i].grad * (p - pold);
00084     }
00085   }
00086 
00087   // save for next step
00088   group.old_pos = group.positions();
00089   return change;
00090 }

colvarvalue colvar::cvc::Jacobian_derivative (   )  const [inline, virtual]
 

Return the previously calculated divergence of the inverse atomic gradients.

Definition at line 252 of file colvarcomp.h.

00253 {
00254   return jd;
00255 }

void colvar::cvc::parse_group (  std::string const &  conf,
char const *  group_key,
cvm::atom_group &  group,
bool  optional = false
) 
 

Within the constructor, make a group parse its own options from the provided configuration string.

Definition at line 41 of file colvarcomp.C.

References colvarmodule::fatal_error(), colvarparse::key_lookup(), and colvarmodule::atom_group::parse().

Referenced by colvar::angle::angle(), colvar::dihedral::dihedral(), colvar::distance::distance(), colvar::distance_z::distance_z(), colvar::eigenvector::eigenvector(), colvar::gyration::gyration(), and colvar::orientation::orientation().

00045 {
00046   if (key_lookup (conf, group_key)) {
00047     group.parse (conf, group_key);
00048   } else {
00049     if (! optional) {
00050       cvm::fatal_error ("Error: definition for atom group \""+
00051                       std::string (group_key)+"\" not found.\n");
00052     }
00053   }
00054 }

colvarvalue colvar::cvc::system_force (   )  const [inline, virtual]
 

Return the previously calculated system force.

Definition at line 247 of file colvarcomp.h.

00248 {
00249   return ft;
00250 }

colvarvalue::Type colvar::cvc::type (   )  const [inline]
 

Type of that this cvc provides.

Definition at line 237 of file colvarcomp.h.

References colvarvalue::type(), and x.

Referenced by compare().

00238 {
00239   return x.type();
00240 }

colvarvalue colvar::cvc::value (   )  const [inline, virtual]
 

Return the previously calculated value.

Definition at line 242 of file colvarcomp.h.

Referenced by colvar::alpha_dihedrals::apply_force(), and colvar::alpha_dihedrals::calc_value().

00243 {
00244   return x;
00245 }

Member Data Documentation

bool colvar::cvc::b_debug_gradients
 

If true, calc_gradients() will calculate finite-difference gradients alongside the analytical ones and report their differences.

Definition at line 109 of file colvarcomp.h.

Referenced by cvc().

bool colvar::cvc::b_inverse_gradients
 

If this flag is false (default), inverse gradients (derivatives of atom coordinates with respect to x) are unavailable; it should be set to true by the constructor of each derived object capable of calculating them.

Definition at line 120 of file colvarcomp.h.

bool colvar::cvc::b_Jacobian_derivative
 

If this flag is false (default), the Jacobian derivative (divergence of the inverse gradients) is unavailable; it should be set to true by the constructor of each derived object capable of calculating it.

Definition at line 126 of file colvarcomp.h.

bool colvar::cvc::b_periodic
 

Definition at line 82 of file colvarcomp.h.

colvarvalue colvar::cvc::ft [protected]
 

Calculated system force (Note: this is calculated from the total atomic forces read from the program, subtracting fromt the "internal" forces of the system the "external" forces from the colvar biases).

Definition at line 227 of file colvarcomp.h.

std::string colvar::cvc::function_type
 

Description of the type of collective variable.

Normally this string is set by the parent object within its constructor, when all objects are initialized; therefore the main "config string" constructor does not need to define it. If a is initialized and/or a different constructor is used, this variable definition should be set within the constructor.

Definition at line 68 of file colvarcomp.h.

Referenced by calc_force_invgrads(), and calc_Jacobian_derivative().

colvarvalue colvar::cvc::jd [protected]
 

Calculated Jacobian derivative (divergence of the inverse gradients): serves to calculate the phase space correction.

Definition at line 231 of file colvarcomp.h.

std::string colvar::cvc::name
 

The name of the object (helps to identify this cvc instance when debugging).

Definition at line 58 of file colvarcomp.h.

cvm::real colvar::cvc::period
 

Period of this cvc value, (default: 0.0, non periodic).

Definition at line 80 of file colvarcomp.h.

Referenced by cvc().

cvm::real colvar::cvc::sup_coeff
 

Coefficient in the polynomial superposition (default: 1.0).

Definition at line 75 of file colvarcomp.h.

Referenced by cvc().

int colvar::cvc::sup_np
 

Exponent in the polynomial superposition (default: 1).

Definition at line 77 of file colvarcomp.h.

Referenced by cvc().

colvarvalue colvar::cvc::x [protected]
 

Cached value.

Definition at line 218 of file colvarcomp.h.

Referenced by fdiff_change(), and type().

colvarvalue colvar::cvc::x_old [protected]
 

Value at the previous step.

Definition at line 221 of file colvarcomp.h.

The documentation for this class was generated from the following files:
Generated on Mon Nov 23 04:59:32 2009 for NAMD by  doxygen 1.3.9.1