Collective Variables Module - Developer Documentation
colvarmodule.h
Go to the documentation of this file.
1 // -*- c++ -*-
2 
3 #ifndef COLVARMODULE_H
4 #define COLVARMODULE_H
5 
6 #include "colvars_version.h"
7 
8 #ifndef COLVARS_DEBUG
9 #define COLVARS_DEBUG false
10 #endif
11 
18 
27 #define COLVARS_OK 0
28 #define COLVARS_ERROR 1
29 #define COLVARS_NOT_IMPLEMENTED (1<<1)
30 #define INPUT_ERROR (1<<2) // out of bounds or inconsistent input
31 #define BUG_ERROR (1<<3) // Inconsistent state indicating bug
32 #define FILE_ERROR (1<<4)
33 #define MEMORY_ERROR (1<<5)
34 #define FATAL_ERROR (1<<6) // Should be set, or not, together with other bits
35 #define DELETE_COLVARS (1<<7) // Instruct the caller to delete cvm
36 #define COLVARS_NO_SUCH_FRAME (1<<8) // Cannot load the requested frame
37 
38 #include <iostream>
39 #include <iomanip>
40 #include <fstream>
41 #include <sstream>
42 #include <string>
43 #include <vector>
44 #include <list>
45 
46 class colvarparse;
47 class colvar;
48 class colvarbias;
49 class colvarproxy;
50 class colvarscript;
51 
52 
62 class colvarmodule {
63 
64 private:
65 
67  colvarmodule();
68 
69 public:
70 
71  friend class colvarproxy;
72  // TODO colvarscript should be unaware of colvarmodule's internals
73  friend class colvarscript;
74 
76  typedef double real;
77 
79  static inline real integer_power(real const &x, int const n)
80  {
81  // Original code: math_special.h in LAMMPS
82  double yy, ww;
83  if (x == 0.0) return 0.0;
84  int nn = (n > 0) ? n : -n;
85  ww = x;
86  for (yy = 1.0; nn != 0; nn >>= 1, ww *=ww) {
87  if (nn & 1) yy *= ww;
88  }
89  return (n > 0) ? yy : 1.0/yy;
90  }
91 
93  typedef int residue_id;
94 
95  class rvector;
96  template <class T> class vector1d;
97  template <class T> class matrix2d;
98  class quaternion;
99  class rotation;
100 
103  typedef rvector atom_pos;
104 
106  class rmatrix;
107 
108  // allow these classes to access protected data
109  class atom;
110  class atom_group;
111  friend class atom;
112  friend class atom_group;
113  typedef std::vector<atom>::iterator atom_iter;
114  typedef std::vector<atom>::const_iterator atom_const_iter;
115 
118 protected:
119 
120  static int errorCode;
121 
122 public:
123 
124  static void set_error_bits(int code);
125 
126  static bool get_error_bit(int code);
127 
128  static inline int get_error()
129  {
130  return errorCode;
131  }
132 
133  static void clear_error();
134 
135 
137  static long it;
139  static long it_restart;
140 
142  static inline long step_relative()
143  {
144  return it - it_restart;
145  }
146 
149  static inline long step_absolute()
150  {
151  return it;
152  }
153 
157 
162 
163 private:
164 
166  std::string cvm_output_prefix;
167 
168 public:
170  static inline std::string &output_prefix()
171  {
173  return cv->cvm_output_prefix;
174  }
175 
176 private:
177 
179  std::vector<colvar *> colvars;
180 
182  std::vector<colvar *> colvars_active;
183 
186  std::vector<colvar *> colvars_smp;
188  std::vector<int> colvars_smp_items;
189 
191  std::vector<atom_group *> named_atom_groups;
192 public:
195  named_atom_groups.push_back(ag);
196  }
197 
199  std::vector<colvar *> *variables();
200 
201  /* TODO: implement named CVCs
203  static std::vector<cvc *> cvcs;
205  inline void register_cvc(cvc *p) {
206  cvcs.push_back(p);
207  }
208  */
209 
211  std::vector<colvar *> *variables_active();
212 
215  std::vector<colvar *> *variables_active_smp();
216 
218  std::vector<int> *variables_active_smp_items();
219 
221  std::vector<colvarbias *> biases;
222 
225 
226 private:
227 
229  std::vector<colvarbias *> biases_active_;
230 
231 public:
232 
234  std::vector<colvarbias *> *biases_active();
235 
237  static inline bool debug()
238  {
239  return COLVARS_DEBUG;
240  }
241 
243  size_t size() const;
244 
248 
250  ~colvarmodule();
251 
253  int reset();
254 
256  int read_config_file(char const *config_file_name);
257 
260  int read_config_string(std::string const &conf);
261 
263  int parse_config(std::string &conf);
264 
265  // Parse functions (setup internal data based on a string)
266 
269  static std::istream & getline(std::istream &is, std::string &line);
270 
272  int parse_global_params(std::string const &conf);
273 
275  int parse_colvars(std::string const &conf);
276 
278  int parse_biases(std::string const &conf);
279 
283  int append_new_config(std::string const &conf);
284 
285 private:
286 
289  std::string extra_conf;
290 
292  template <class bias_type>
293  int parse_biases_type(std::string const &conf, char const *keyword);
294 
297  bool check_new_bias(std::string &conf, char const *key);
298 
299 public:
300 
302  int num_biases_feature(int feature_id) const;
303 
305  int num_biases_type(std::string const &type) const;
306 
308  std::vector<std::string> const time_dependent_biases() const;
309 
310 private:
312  int catch_input_errors(int result);
313 
314 public:
315 
316  // "Setup" functions (change internal data based on related data
317  // from the proxy that may change during program execution)
318  // No additional parsing is done within these functions
319 
322  int setup();
323 
325  int setup_input();
326 
328  int setup_output();
329 
331  std::istream & read_restart(std::istream &is);
333  std::ostream & write_restart(std::ostream &os);
334 
336  int open_traj_file(std::string const &file_name);
338  int close_traj_file();
340  std::ostream & write_traj(std::ostream &os);
342  std::ostream & write_traj_label(std::ostream &os);
343 
345  int write_traj_files();
347  int write_restart_file(std::string const &out_name);
349  int write_output_files();
351  static int backup_file(char const *filename);
352 
354  static colvarbias * bias_by_name(std::string const &name);
355 
357  static colvar * colvar_by_name(std::string const &name);
358 
360  static atom_group * atom_group_by_name(std::string const &name);
361 
364  int change_configuration(std::string const &bias_name, std::string const &conf);
365 
367  std::string read_colvar(std::string const &name);
368 
371  real energy_difference(std::string const &bias_name, std::string const &conf);
372 
374  int bias_bin_num(std::string const &bias_name);
376  int bias_current_bin(std::string const &bias_name);
378  int bias_bin_count(std::string const &bias_name, size_t bin_index);
380  int bias_share(std::string const &bias_name);
381 
383  int calc();
384 
386  int calc_colvars();
387 
389  int calc_biases();
390 
392  int update_colvar_forces();
393 
395  int analyze();
396 
399  int read_traj(char const *traj_filename,
400  long traj_read_begin,
401  long traj_read_end);
402 
404  template<typename T> static std::string to_str(T const &x,
405  size_t const &width = 0,
406  size_t const &prec = 0);
408  template<typename T> static std::string to_str(std::vector<T> const &x,
409  size_t const &width = 0,
410  size_t const &prec = 0);
411 
413  static inline std::string wrap_string(std::string const &s,
414  size_t const &nchars)
415  {
416  if (!s.size())
417  return std::string(nchars, ' ');
418  else
419  return ( (s.size() <= size_t(nchars)) ?
420  (s+std::string(nchars-s.size(), ' ')) :
421  (std::string(s, 0, nchars)) );
422  }
423 
425  static size_t const it_width;
427  static size_t const cv_prec;
429  static size_t const cv_width;
431  static size_t const en_prec;
433  static size_t const en_width;
435  static const char * const line_marker;
436 
437 
438  // proxy functions
439 
442  static real unit_angstrom();
443 
445  static real boltzmann();
446 
448  static real temperature();
449 
451  static real dt();
452 
454  static void request_total_force();
455 
457  static void log(std::string const &message);
458 
460  static int fatal_error(std::string const &message);
461 
463  static int error(std::string const &message, int code = COLVARS_ERROR);
464 
466  static void exit(std::string const &message);
467 
468  // Replica exchange commands.
469  static bool replica_enabled();
470  static int replica_index();
471  static int replica_num();
472  static void replica_comm_barrier();
473  static int replica_comm_recv(char* msg_data, int buf_len, int src_rep);
474  static int replica_comm_send(char* msg_data, int msg_len, int dest_rep);
475 
478  static rvector position_distance(atom_pos const &pos1,
479  atom_pos const &pos2);
480 
487  static real position_dist2(atom_pos const &pos1,
488  atom_pos const &pos2);
489 
491  std::list<std::string> index_group_names;
492 
494  std::list<std::vector<int> > index_groups;
495 
497  int read_index_file(char const *filename);
498 
499 
504  static int load_atoms(char const *filename,
505  atom_group &atoms,
506  std::string const &pdb_field,
507  double const pdb_field_value = 0.0);
508 
511  static int load_coords(char const *filename,
512  std::vector<atom_pos> &pos,
513  const std::vector<int> &indices,
514  std::string const &pdb_field,
515  double const pdb_field_value = 0.0);
516 
519  static int load_coords_xyz(char const *filename,
520  std::vector<atom_pos> &pos,
521  const std::vector<int> &indices);
522 
524  static size_t cv_traj_freq;
525 
527  static bool b_analysis;
528 
530  static size_t restart_out_freq;
532  std::string restart_out_name;
533 
535  static real rand_gaussian(void);
536 
537 protected:
538 
540  std::ifstream config_s;
541 
544 
546  std::string cv_traj_name;
547 
549  std::ostream *cv_traj_os;
550 
553 
554 private:
555 
557  size_t depth_s;
558 
560  std::vector<size_t> depth_v;
561 
562 public:
563 
565  static size_t & depth();
566 
568  static void increase_depth();
569 
571  static void decrease_depth();
572 
573  static inline bool scripted_forces()
574  {
575  return use_scripted_forces;
576  }
577 
579  static bool use_scripted_forces;
580 
583 
585  int calc_scripted_forces();
586 
591 
593  static colvarmodule *main();
594 
595 };
596 
597 
600 
601 
602 
603 std::ostream & operator << (std::ostream &os, cvm::rvector const &v);
604 std::istream & operator >> (std::istream &is, cvm::rvector &v);
605 
606 
607 template<typename T> std::string cvm::to_str(T const &x,
608  size_t const &width,
609  size_t const &prec) {
610  std::ostringstream os;
611  if (width) os.width(width);
612  if (prec) {
613  os.setf(std::ios::scientific, std::ios::floatfield);
614  os.precision(prec);
615  }
616  os << x;
617  return os.str();
618 }
619 
620 
621 template<typename T> std::string cvm::to_str(std::vector<T> const &x,
622  size_t const &width,
623  size_t const &prec) {
624  if (!x.size()) return std::string("");
625  std::ostringstream os;
626  if (prec) {
627  os.setf(std::ios::scientific, std::ios::floatfield);
628  }
629  os << "{ ";
630  if (width) os.width(width);
631  if (prec) os.precision(prec);
632  os << x[0];
633  for (size_t i = 1; i < x.size(); i++) {
634  os << ", ";
635  if (width) os.width(width);
636  if (prec) os.precision(prec);
637  os << x[i];
638  }
639  os << " }";
640  return os.str();
641 }
642 
643 
644 #endif
static real integer_power(real const &x, int const n)
Override std::pow with a product for n integer.
Definition: colvarmodule.h:79
int num_biases_feature(int feature_id) const
Return how many biases have this feature enabled.
Definition: colvarmodule.cpp:428
static void request_total_force()
Request calculation of total force from MD engine.
Definition: colvarmodule.cpp:1762
std::ifstream config_s
Configuration file.
Definition: colvarmodule.h:540
static void exit(std::string const &message)
Print a message to the main log and exit normally.
int parse_global_params(std::string const &conf)
Parse the few module&#39;s global parameters.
Definition: colvarmodule.cpp:237
1-dimensional vector of real numbers with four components and a quaternion algebra ...
Definition: colvartypes.h:1020
static long step_absolute()
Definition: colvarmodule.h:149
bool cv_traj_append
Appending to the existing trajectory file?
Definition: colvarmodule.h:552
std::vector< colvarbias * > * biases_active()
Array of active collective variable biases.
Definition: colvarmodule.cpp:103
static long it
Current step number.
Definition: colvarmodule.h:137
int bias_bin_num(std::string const &bias_name)
Give the total number of bins for a given bias.
Definition: colvarmodule.cpp:594
static real rand_gaussian(void)
Pseudo-random number with Gaussian distribution.
Definition: colvarmodule.cpp:1779
int open_traj_file(std::string const &file_name)
Open a trajectory file if requested (and leave it open)
Definition: colvarmodule.cpp:1423
static real dt()
Time step of MD integrator (fs)
Definition: colvarmodule.cpp:1756
static real debug_gradients_step_size
Finite difference step size (if there is no dynamics, or if gradients need to be tested independently...
Definition: colvarmodule.h:161
int parse_colvars(std::string const &conf)
Parse and initialize collective variables.
Definition: colvarmodule.cpp:287
static bool use_scripted_forces
Use scripted colvars forces?
Definition: colvarmodule.h:579
int update_colvar_forces()
Integrate bias and restraint forces, send colvar forces to atoms.
Definition: colvarmodule.cpp:841
static size_t const en_prec
Number of digits to represent the collective variables energy.
Definition: colvarmodule.h:431
static atom_group * atom_group_by_name(std::string const &name)
Look up a named atom group by name; returns NULL if not found.
Definition: colvarmodule.cpp:514
Stores numeric id, mass and all mutable data for an atom, mostly used by a cvc.
Definition: colvaratoms.h:21
static size_t cv_traj_freq
Frequency for collective variables trajectory output.
Definition: colvarmodule.h:524
std::vector< colvarbias * > biases
Array of collective variable biases.
Definition: colvarmodule.h:221
int num_biases_type(std::string const &type) const
Return how many biases are defined with this type.
Definition: colvarmodule.cpp:443
static colvarproxy * proxy
Pointer to the proxy object, used to retrieve atomic data from the hosting program; it is static in o...
Definition: colvarmodule.h:590
std::vector< int > * variables_active_smp_items()
Indexes of the items to calculate for each colvar.
Definition: colvarmodule.cpp:97
int write_restart_file(std::string const &out_name)
Write a state file useful to resume the simulation.
Definition: colvarmodule.cpp:926
std::vector< colvar * > * variables_active_smp()
Definition: colvarmodule.cpp:91
int calc_biases()
Calculate biases.
Definition: colvarmodule.cpp:783
vector of real numbers with three components
Definition: colvartypes.h:714
int write_traj_files()
Write all trajectory files.
Definition: colvarmodule.cpp:940
static int load_coords_xyz(char const *filename, std::vector< atom_pos > &pos, const std::vector< int > &indices)
Load the coordinates for a group of atoms from an XYZ file.
Definition: colvarmodule.cpp:1694
std::string cv_traj_name
Name of the trajectory file.
Definition: colvarmodule.h:546
std::ostream * cv_traj_os
Collective variables output trajectory file.
Definition: colvarmodule.h:549
Collective variables module (main class)
Definition: colvarmodule.h:62
real total_bias_energy
Energy of built-in and scripted biases, summed per time-step.
Definition: colvarmodule.h:224
int calc()
Main worker function.
Definition: colvarmodule.cpp:647
static long it_restart
Starting step number for this run.
Definition: colvarmodule.h:139
static colvar * colvar_by_name(std::string const &name)
Look up a colvar by name; returns NULL if not found.
Definition: colvarmodule.cpp:500
int setup_output()
(Re)initialize the output trajectory and state file (does not write it yet)
Definition: colvarmodule.cpp:1108
Interface between the collective variables module and the simulation or analysis program (NAMD...
Definition: colvarproxy.h:529
int read_index_file(char const *filename)
Read a Gromacs .ndx file.
Definition: colvarmodule.cpp:1603
int append_new_config(std::string const &conf)
Add new configuration during parsing (e.g. to implement back-compatibility); cannot be nested...
Definition: colvarmodule.cpp:230
colvarmodule cvm
Shorthand for the frequently used type prefix.
Definition: colvarmodule.h:599
int read_config_file(char const *config_file_name)
Open a config file, load its contents, and pass it to config_string()
Definition: colvarmodule.cpp:115
static std::istream & getline(std::istream &is, std::string &line)
Definition: colvarmodule.cpp:162
int write_output_files()
Write all other output files.
Definition: colvarmodule.cpp:1288
static int errorCode
Definition: colvarmodule.h:120
int calc_scripted_forces()
Calculate the energy and forces of scripted biases.
Definition: colvarmodule.cpp:908
static int load_atoms(char const *filename, atom_group &atoms, std::string const &pdb_field, double const pdb_field_value=0.0)
Create atoms from a file.
Definition: colvarmodule.cpp:1663
double real
Defining an abstract real number allows to switch precision.
Definition: colvarmodule.h:76
static int error(std::string const &message, int code=COLVARS_ERROR)
Print a message to the main log and set global error code.
Definition: colvarmodule.cpp:1587
int change_configuration(std::string const &bias_name, std::string const &conf)
Definition: colvarmodule.cpp:528
rvector atom_pos
Atom position (different type name from rvector, to make possible future PBC-transparent implementati...
Definition: colvarmodule.h:99
int calc_colvars()
Calculate collective variables.
Definition: colvarmodule.cpp:691
static std::string & output_prefix()
Accessor for the above.
Definition: colvarmodule.h:170
int close_traj_file()
Close it (note: currently unused)
Definition: colvarmodule.cpp:1450
Collective variable bias, base class.
Definition: colvarbias.h:12
static int load_coords(char const *filename, std::vector< atom_pos > &pos, const std::vector< int > &indices, std::string const &pdb_field, double const pdb_field_value=0.0)
Load the coordinates for a group of atoms from a file (PDB or XYZ)
static int backup_file(char const *filename)
Backup a file before writing it.
Definition: colvarmodule.cpp:1282
std::vector< colvar * > * variables()
Array of collective variables.
Definition: colvarmodule.cpp:79
static int fatal_error(std::string const &message)
Print a message to the main log and exit with error code.
Definition: colvarmodule.cpp:1595
static size_t & depth()
Get the current object depth in the hierarchy.
Definition: colvarmodule.cpp:1543
std::list< std::vector< int > > index_groups
Groups from a Gromacs .ndx file read at startup.
Definition: colvarmodule.h:494
std::ostream & write_traj(std::ostream &os)
Write in the trajectory file.
Definition: colvarmodule.cpp:1489
bool it_restart_from_state_file
Definition: colvarmodule.h:156
std::string restart_out_name
Output restart file name.
Definition: colvarmodule.h:532
int reset()
Actual function called by the destructor.
Definition: colvarmodule.cpp:1032
int setup_input()
(Re)initialize and (re)read the input state file calling read_restart()
Definition: colvarmodule.cpp:1068
2-dimensional array of real numbers with three components along each dimension (works with colvarmodu...
Definition: colvartypes.h:892
std::ostream & write_restart(std::ostream &os)
Write the output restart file.
Definition: colvarmodule.cpp:1388
static std::string wrap_string(std::string const &s, size_t const &nchars)
Reduce the number of characters in a string.
Definition: colvarmodule.h:413
std::list< std::string > index_group_names
Names of groups from a Gromacs .ndx file to be read at startup.
Definition: colvarmodule.h:491
int read_traj(char const *traj_filename, long traj_read_begin, long traj_read_end)
Read a collective variable trajectory (post-processing only, not called at runtime) ...
Definition: colvarmodule.cpp:1319
~colvarmodule()
Destructor.
Definition: colvarmodule.cpp:1012
Definition: colvarscript.h:21
Arbitrary size array (two dimensions) suitable for linear algebra operations (i.e. for floating point numbers it can be used with library functions)
Definition: colvarmodule.h:97
std::string read_colvar(std::string const &name)
Read a colvar value.
Definition: colvarmodule.cpp:546
std::vector< std::string > const time_dependent_biases() const
Return the names of time-dependent biases with forces enabled.
Definition: colvarmodule.cpp:458
int bias_current_bin(std::string const &bias_name)
Calculate the bin index for a given bias.
Definition: colvarmodule.cpp:577
static size_t restart_out_freq
Frequency for saving output restarts.
Definition: colvarmodule.h:530
static colvarbias * bias_by_name(std::string const &name)
Look up a bias by name; returns NULL if not found.
Definition: colvarmodule.cpp:486
static bool b_analysis
True if only analysis is performed and not a run.
Definition: colvarmodule.h:527
size_t size() const
How many objects are configured yet?
Definition: colvarmodule.cpp:109
static real position_dist2(atom_pos const &pos1, atom_pos const &pos2)
Get the square distance between two positions (with periodic boundary conditions handled transparentl...
Definition: colvarmodule.cpp:1773
int residue_id
Residue identifier.
Definition: colvarmodule.h:93
int setup()
Definition: colvarmodule.cpp:1000
static const char *const line_marker
Line separator in the log output.
Definition: colvarmodule.h:435
static std::string to_str(T const &x, size_t const &width=0, size_t const &prec=0)
Quick conversion of an object to a string.
Definition: colvarmodule.h:607
std::vector< colvar * > * variables_active()
Collective variables with the active flag on.
Definition: colvarmodule.cpp:85
A collective variable (main class); to be defined, it needs at least one object of a derived class of...
Definition: colvar.h:42
static bool scripting_after_biases
Wait for all biases before calculating scripted forces?
Definition: colvarmodule.h:582
real energy_difference(std::string const &bias_name, std::string const &conf)
Definition: colvarmodule.cpp:561
int read_config_string(std::string const &conf)
Parse a config string assuming it is a complete configuration (i.e. calling all parse functions) ...
Definition: colvarmodule.cpp:144
static rvector position_distance(atom_pos const &pos1, atom_pos const &pos2)
Get the distance between two atomic positions with pbcs handled correctly.
Definition: colvarmodule.cpp:1767
static colvarmodule * main()
Access the one instance of the Colvars module.
Definition: colvarmodule.cpp:73
int parse_biases(std::string const &conf)
Parse and initialize collective variable biases.
Definition: colvarmodule.cpp:370
static real temperature()
Temperature of the simulation (K)
Definition: colvarmodule.cpp:1750
int analyze()
Perform analysis.
Definition: colvarmodule.cpp:969
static size_t const it_width
Number of characters to represent a time step.
Definition: colvarmodule.h:425
static long step_relative()
Return the current step number from the beginning of this run.
Definition: colvarmodule.h:142
static size_t const cv_prec
Number of digits to represent a collective variables value(s)
Definition: colvarmodule.h:427
static size_t const en_width
Number of characters to represent the collective variables energy.
Definition: colvarmodule.h:433
Base class containing parsing functions; all objects which need to parse input inherit from this...
Definition: colvarparse.h:18
static void log(std::string const &message)
Print a message to the main log.
Definition: colvarmodule.cpp:1518
A rotation between two sets of coordinates (for the moment a wrapper for colvarmodule::quaternion) ...
Definition: colvartypes.h:1369
void register_named_atom_group(atom_group *ag)
Register a named atom group into named_atom_groups.
Definition: colvarmodule.h:194
colvarparse * parse
Configuration file parser object.
Definition: colvarmodule.h:543
static void increase_depth()
Increase the depth (number of indentations in the output)
Definition: colvarmodule.cpp:1529
std::ostream & write_traj_label(std::ostream &os)
Write explanatory labels in the trajectory file.
Definition: colvarmodule.cpp:1460
Arbitrary size array (one dimensions) suitable for linear algebra operations (i.e. for floating point numbers it can be used with library functions)
Definition: colvarmodule.h:96
static real boltzmann()
Boltmann constant.
Definition: colvarmodule.cpp:1744
static size_t const cv_width
Number of characters to represent a collective variables value(s)
Definition: colvarmodule.h:429
static real unit_angstrom()
Value of the unit for atomic coordinates with respect to angstroms (used by some variables for hard-c...
Definition: colvarmodule.cpp:1738
std::istream & read_restart(std::istream &is)
Read the input restart file.
Definition: colvarmodule.cpp:1155
static void decrease_depth()
Decrease the depth (number of indentations in the output)
Definition: colvarmodule.cpp:1535
static bool debug()
Whether debug output should be enabled (compile-time option)
Definition: colvarmodule.h:237
Group of atom objects, mostly used by a cvc object to gather all atomic data.
Definition: colvaratoms.h:142
int parse_config(std::string &conf)
Parse a "clean" config string (no comments)
Definition: colvarmodule.cpp:181