Collective Variables Module - Developer Documentation
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Friends Pages
Public Member Functions | Public Attributes | Static Public Attributes | Protected Attributes | List of all members
colvar::cvc Class Referenceabstract

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

#include <colvarcomp.h>

Inheritance diagram for colvar::cvc:
Inheritance graph
[legend]
Collaboration diagram for colvar::cvc:
Collaboration graph
[legend]

Public Member Functions

 cvc (std::string const &conf)
 Constructor. More...
 
cvm::atom_groupparse_group (std::string const &conf, char const *group_key, bool optional=false)
 Within the constructor, make a group parse its own options from the provided configuration string Returns reference to new group.
 
virtual int init_total_force_params (std::string const &conf)
 Parse options pertaining to total force calculation.
 
int setup ()
 After construction, set data related to dependency handling.
 
 cvc ()
 Default constructor (used when cvc objects are declared within other ones)
 
virtual ~cvc ()
 Destructor.
 
virtual std::vector< feature * > & features ()
 Implementation of the feature list accessor for colvar.
 
virtual void read_data ()
 Obtain data needed for the calculation for the backend.
 
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 debug_gradients (cvm::atom_group *group)
 Calculate finite-difference gradients alongside the analytical ones, for each Cartesian component.
 
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.
 
colvarvalue const & value () const
 Return the previously calculated value.
 
colvarvalue const & total_force () const
 Return the previously calculated total force.
 
colvarvalue const & 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 ft member is not altered by this function) More...
 
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) More...
 
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 void wrap (colvarvalue &x) const
 Wrapp value (for periodic/symmetric cvcs)
 
- Public Member Functions inherited from colvarparse
 colvarparse (const std::string &conf)
 Constructor that stores the object's config string.
 
void init ()
 Set the object ready to parse a new configuration string.
 
void init (const std::string &conf)
 Set a new config string for this object.
 
const std::string & get_config ()
 
int check_keywords (std::string &conf, char const *key)
 Check that all the keywords within "conf" are in the list of allowed keywords; this will invoke strip_values() first and then loop over all words.
 
void clear_keyword_registry ()
 Use this after parsing a config string (note that check_keywords() calls it already)
 
bool get_keyval (std::string const &conf, char const *key, int &value, int const &def_value=(int) 0, Parse_Mode const parse_mode=parse_normal)
 
bool get_keyval (std::string const &conf, char const *key, size_t &value, size_t const &def_value=(size_t) 0, Parse_Mode const parse_mode=parse_normal)
 
bool get_keyval (std::string const &conf, char const *key, long &value, long const &def_value=0, Parse_Mode const parse_mode=parse_normal)
 
bool get_keyval (std::string const &conf, char const *key, std::string &value, std::string const &def_value=std::string(""), Parse_Mode const parse_mode=parse_normal)
 
bool get_keyval (std::string const &conf, char const *key, cvm::real &value, cvm::real const &def_value=(cvm::real) 0.0, Parse_Mode const parse_mode=parse_normal)
 
bool get_keyval (std::string const &conf, char const *key, cvm::rvector &value, cvm::rvector const &def_value=cvm::rvector(), Parse_Mode const parse_mode=parse_normal)
 
bool get_keyval (std::string const &conf, char const *key, cvm::quaternion &value, cvm::quaternion const &def_value=cvm::quaternion(), Parse_Mode const parse_mode=parse_normal)
 
bool get_keyval (std::string const &conf, char const *key, colvarvalue &value, colvarvalue const &def_value=colvarvalue(colvarvalue::type_notset), Parse_Mode const parse_mode=parse_normal)
 
bool get_keyval (std::string const &conf, char const *key, bool &value, bool const &def_value=false, Parse_Mode const parse_mode=parse_normal)
 
bool get_keyval (std::string const &conf, char const *key, std::vector< int > &values, std::vector< int > const &def_values=std::vector< int >(0,(int) 0), Parse_Mode const parse_mode=parse_normal)
 
bool get_keyval (std::string const &conf, char const *key, std::vector< size_t > &values, std::vector< size_t > const &def_values=std::vector< size_t >(0,(size_t) 0), Parse_Mode const parse_mode=parse_normal)
 
bool get_keyval (std::string const &conf, char const *key, std::vector< long > &values, std::vector< long > const &def_values=std::vector< long >(0,(long) 0), Parse_Mode const parse_mode=parse_normal)
 
bool get_keyval (std::string const &conf, char const *key, std::vector< std::string > &values, std::vector< std::string > const &def_values=std::vector< std::string >(0, std::string("")), Parse_Mode const parse_mode=parse_normal)
 
bool get_keyval (std::string const &conf, char const *key, std::vector< cvm::real > &values, std::vector< cvm::real > const &def_values=std::vector< cvm::real >(0,(cvm::real) 0.0), Parse_Mode const parse_mode=parse_normal)
 
bool get_keyval (std::string const &conf, char const *key, std::vector< cvm::rvector > &values, std::vector< cvm::rvector > const &def_values=std::vector< cvm::rvector >(0, cvm::rvector()), Parse_Mode const parse_mode=parse_normal)
 
bool get_keyval (std::string const &conf, char const *key, std::vector< cvm::quaternion > &values, std::vector< cvm::quaternion > const &def_values=std::vector< cvm::quaternion >(0, cvm::quaternion()), Parse_Mode const parse_mode=parse_normal)
 
bool get_keyval (std::string const &conf, char const *key, std::vector< colvarvalue > &values, std::vector< colvarvalue > const &def_values=std::vector< colvarvalue >(0, colvarvalue(colvarvalue::type_notset)), Parse_Mode const parse_mode=parse_normal)
 
bool key_lookup (std::string const &conf, char const *key, std::string &data=dummy_string, size_t &save_pos=dummy_pos)
 Low-level function for parsing configuration strings; automatically adds the requested keyword to the list of valid ones. More...
 
bool brace_check (std::string const &conf, size_t const start_pos=0)
 Check if the content of the file has matching braces.
 
- Public Member Functions inherited from colvardeps
void init_feature (int feature_id, const char *description, feature_type type=f_type_not_set)
 Pair a numerical feature ID with a description and type.
 
bool is_dynamic (int id)
 
bool is_static (int id)
 
bool is_user (int id)
 
void add_child (colvardeps *child)
 
void remove_child (colvardeps *child)
 
void remove_all_children ()
 
bool is_enabled (int f=f_cv_active) const
 
bool is_available (int f=f_cv_active) const
 
void provide (int feature_id, bool truefalse=true)
 
void set_enabled (int feature_id, bool truefalse=true)
 
int enable (int f, bool dry_run=false, bool toplevel=true)
 
virtual int refresh_deps ()
 
void init_cvb_requires ()
 
void init_cv_requires ()
 
void init_cvc_requires ()
 
void init_ag_requires ()
 
void print_state ()
 print all enabled features and those of children, for debugging
 

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. More...
 
cvm::real sup_coeff
 Coefficient in the polynomial combination (default: 1.0)
 
int sup_np
 Exponent in the polynomial combination (default: 1)
 
bool b_periodic
 Is this a periodic component?
 
cvm::real period
 Period of this cvc value, (default: 0.0, non periodic)
 
cvm::real wrap_center
 If the component is periodic, wrap around this value (default: 0.0)
 
std::vector< cvm::atom_group * > atom_groups
 Pointers to all atom groups, to let colvars collect info e.g. atomic gradients.
 
bool b_try_scalable
 Whether or not this CVC will be computed in parallel whenever possible.
 
- Public Attributes inherited from colvardeps
std::string description
 

Static Public Attributes

static std::vector< feature * > cvc_features
 Implementation of the feature list for colvar.
 
- Static Public Attributes inherited from colvarparse
static std::string const white_space = " \t"
 Accepted white space delimiters, used in key_lookup()
 
static std::string dummy_string = ""
 Used as a default argument by key_lookup.
 
static size_t dummy_pos = 0
 Used as a default argument by key_lookup.
 

Protected Attributes

colvarvalue x
 Cached value.
 
colvarvalue x_old
 Value at the previous step.
 
colvarvalue ft
 Calculated total 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.
 
- Protected Attributes inherited from colvarparse
std::list< std::string > allowed_keywords
 List of legal keywords for this object: this is updated by each call to colvarparse::get_keyval() or colvarparse::key_lookup()
 
std::list< size_t > data_begin_pos
 List of delimiters for the values of each keyword in the configuration string; all keywords will be stripped of their values before the keyword check is performed.
 
std::list< size_t > data_end_pos
 List of delimiters for the values of each keyword in the configuration string; all keywords will be stripped of their values before the keyword check is performed.
 
bool save_delimiters
 Whether or not to accumulate data_begin_pos and data_end_pos in key_lookup(); it may be useful to disable this after the constructor is called, because other files may be read (e.g. restart) that would mess up the registry; in any case, nothing serious happens until check_keywords() is invoked (which should happen only right after construction)
 
std::string config_string
 Configuration string of the object.
 

Additional Inherited Members

- Public Types inherited from colvarparse
enum  Parse_Mode { parse_normal, parse_silent }
 How a keyword is parsed in a string. More...
 
- Public Types inherited from colvardeps
enum  features_biases {
  f_cvb_active, f_cvb_apply_force, f_cvb_get_total_force, f_cvb_history_dependent,
  f_cvb_scalar_variables, f_cvb_calc_pmf, f_cvb_ntot
}
 
enum  features_colvar {
  f_cv_active, f_cv_gradient, f_cv_collect_gradient, f_cv_fdiff_velocity,
  f_cv_total_force, f_cv_total_force_calc, f_cv_subtract_applied_force, f_cv_Jacobian,
  f_cv_hide_Jacobian, f_cv_extended_Lagrangian, f_cv_Langevin, f_cv_output_energy,
  f_cv_output_value, f_cv_output_velocity, f_cv_output_applied_force, f_cv_output_total_force,
  f_cv_lower_boundary, f_cv_upper_boundary, f_cv_grid, f_cv_runave,
  f_cv_corrfunc, f_cv_scripted, f_cv_periodic, f_cv_scalar,
  f_cv_linear, f_cv_homogeneous, f_cv_ntot
}
 
enum  features_cvc {
  f_cvc_active, f_cvc_scalar, f_cvc_gradient, f_cvc_inv_gradient,
  f_cvc_debug_gradient, f_cvc_Jacobian, f_cvc_one_site_total_force, f_cvc_com_based,
  f_cvc_scalable, f_cvc_scalable_com, f_cvc_ntot
}
 
enum  features_atomgroup {
  f_ag_active, f_ag_center, f_ag_rotate, f_ag_fitting_group,
  f_ag_fit_gradient_group, f_ag_fit_gradient_ref, f_ag_atom_forces, f_ag_scalable,
  f_ag_scalable_com, f_ag_ntot
}
 
- Static Public Member Functions inherited from colvarparse
static std::string to_lower_cppstr (std::string const &in)
 Return a lowercased copy of the string.
 
static std::istream & getline_nocomments (std::istream &is, std::string &s)
 Works as std::getline() but also removes everything between a comment character and the following newline.
 
- Protected Member Functions inherited from colvarparse
void add_keyword (char const *key)
 Add a new valid keyword to the list.
 
void strip_values (std::string &conf)
 Remove all the values from the config string.
 
template<typename TYPE >
bool _get_keyval_scalar_ (std::string const &conf, char const *key, TYPE &value, TYPE const &def_value, Parse_Mode const parse_mode)
 
bool _get_keyval_scalar_string_ (std::string const &conf, char const *key, std::string &value, std::string const &def_value, Parse_Mode const parse_mode)
 
template<typename TYPE >
bool _get_keyval_vector_ (std::string const &conf, char const *key, std::vector< TYPE > &values, std::vector< TYPE > const &def_values, Parse_Mode const parse_mode)
 
- Protected Member Functions inherited from colvardeps
bool get_keyval_feature (colvarparse *cvp, std::string const &conf, char const *key, int feature_id, bool const &def_value, colvarparse::Parse_Mode const parse_mode=colvarparse::parse_normal)
 Parse a keyword and enable a feature accordingly.
 

Detailed Description

Colvar component (base class); most implementations of cvc utilize one or more colvarmodule::atom or colvarmodule::atom_group objects to access atoms.

A cvc 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 colvar class already serves this purpose).

No restriction is set to what kind of calculation a cvc object performs (usually calculate an analytical function of atomic coordinates). The only constraint is that the value calculated is implemented as a colvarvalue 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 colvar object.

If you wish to implement a new collective variable component, you should write your own class by inheriting directly from cvc, or one of its derived classes (for instance, distance 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
  1. add a call to the parser in colvar.C, within the function colvar::colvar()
  1. declare the class in colvarcomp.h
  1. 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().

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
confContents of the configuration file pertaining to this cvc

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 ft member is not altered by this function)

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

Parameters
cvforceThe collective variable force, usually coming from the biases and eventually manipulated by the parent colvar object

Implemented in colvar::cartesian, colvar::rmsd, colvar::spin_angle, colvar::tilt, colvar::orientation_proj, colvar::orientation_angle, colvar::orientation, colvar::dihedPC, colvar::alpha_angles, colvar::h_bond, colvar::groupcoordnum, colvar::selfcoordnum, colvar::coordnum, colvar::dihedral, colvar::dipole_angle, colvar::angle, colvar::eigenvector, colvar::inertia_z, colvar::inertia, colvar::gyration, colvar::distance_pairs, colvar::distance_inv, colvar::distance_xy, colvar::distance_z, colvar::distance_dir, colvar::distance_vec, and colvar::distance.

cvm::real colvar::cvc::dist2 ( colvarvalue const &  x1,
colvarvalue const &  x2 
) const
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 colvarvalue 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 colvarvalue 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 colvarvalue type.

Reimplemented in colvar::rmsd, colvar::spin_angle, colvar::tilt, colvar::orientation_proj, colvar::orientation_angle, colvar::orientation, colvar::dihedPC, colvar::alpha_angles, colvar::h_bond, colvar::groupcoordnum, colvar::selfcoordnum, colvar::coordnum, colvar::dihedral, colvar::dipole_angle, colvar::angle, colvar::eigenvector, colvar::inertia_z, colvar::inertia, colvar::gyration, colvar::distance_inv, colvar::distance_xy, colvar::distance_z, colvar::distance_dir, colvar::distance_vec, and colvar::distance.

Member Data Documentation

std::string colvar::cvc::function_type

Description of the type of collective variable.

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


The documentation for this class was generated from the following files: