Collective Variables Module - Developer Documentation
colvardeps.h
1 // -*- c++ -*-
2 
3 // This file is part of the Collective Variables module (Colvars).
4 // The original version of Colvars and its updates are located at:
5 // https://github.com/Colvars/colvars
6 // Please update all Colvars source files before making any changes.
7 // If you wish to distribute your changes, please submit them to the
8 // Colvars repository at GitHub.
9 
10 #ifndef COLVARDEPS_H
11 #define COLVARDEPS_H
12 
13 #include "colvarmodule.h"
14 #include "colvarparse.h"
15 
34 class colvardeps {
35 public:
36 
37  colvardeps();
38  virtual ~colvardeps();
39 
40  // Subclasses should initialize the following members:
41 
42  std::string description; // reference to object name (cv, cvc etc.)
43 
45  // since the feature class only contains static properties
46  struct feature_state {
47  feature_state(bool a, bool e)
48  : available(a), enabled(e), ref_count(0) {}
49 
51  bool available;
55  bool enabled; // see if this should be private depending on implementation
56 
57  // bool enabledOnce; // this should trigger an update when object is evaluated
58 
63  int ref_count;
68  std::vector<int> alternate_refs;
69  };
70 
71 protected:
78 
80  std::vector<feature_state> feature_states;
81 
83  enum feature_type {
84  f_type_not_set,
85  f_type_dynamic,
86  f_type_user,
87  f_type_static
88  };
89 
90 public:
92  inline int get_time_step_factor() const {return time_step_factor;}
93 
95  void init_feature(int feature_id, const char *description, feature_type type);
96 
99  class feature {
100 
101  public:
102  feature() : type(f_type_not_set) {}
103  ~feature() {}
104 
105  std::string description; // Set by derived object initializer
106 
107  // features that this feature requires in the same object
108  // NOTE: we have no safety mechanism against circular dependencies, however, they would have to be internal to an object (ie. requires_self or requires_alt)
109  std::vector<int> requires_self;
110 
111  // Features that are incompatible, ie. required disabled
112  // if enabled, they will cause a dependency failure (they will not be disabled)
113  // To enforce these dependencies regardless of the order in which they
114  // are enabled, they are always set in a symmetric way, so whichever is enabled
115  // second will cause the dependency to fail
116  std::vector<int> requires_exclude;
117 
118  // sets of features that are required in an alternate way
119  // when parent feature is enabled, if none are enabled, the first one listed that is available will be enabled
120  std::vector<std::vector<int> > requires_alt;
121 
122  // features that this feature requires in children
123  std::vector<int> requires_children;
124 
125  inline bool is_dynamic() { return type == f_type_dynamic; }
126  inline bool is_static() { return type == f_type_static; }
127  inline bool is_user() { return type == f_type_user; }
130  };
131 
132  inline bool is_not_set(int id) { return features()[id]->type == f_type_not_set; }
133  inline bool is_dynamic(int id) { return features()[id]->type == f_type_dynamic; }
134  inline bool is_static(int id) { return features()[id]->type == f_type_static; }
135  inline bool is_user(int id) { return features()[id]->type == f_type_user; }
136 
137  // Accessor to array of all features with deps, static in most derived classes
138  // Subclasses with dynamic dependency trees may override this
139  // with a non-static array
140  // Intermediate classes (colvarbias and colvarcomp, which are also base classes)
141  // implement this as virtual to allow overriding
142  virtual const std::vector<feature *> &features() const = 0;
143  virtual std::vector<feature *>&modify_features() = 0;
144 
145  void add_child(colvardeps *child);
146 
147  void remove_child(colvardeps *child);
148 
151  void remove_all_children();
152 
153 private:
154 
158  std::vector<colvardeps *> children;
159 
162  std::vector<colvardeps *> parents;
163 
164 public:
165  // Checks whether given feature is enabled
166  // Defaults to querying f_*_active
167  inline bool is_enabled(int f = f_cv_active) const {
168  return feature_states[f].enabled;
169  }
170 
171  // Checks whether given feature is available
172  // Defaults to querying f_*_active
173  inline bool is_available(int f = f_cv_active) const {
174  return feature_states[f].available;
175  }
176 
180  void provide(int feature_id, bool truefalse = true);
181 
183  void set_enabled(int feature_id, bool truefalse = true);
184 
185 protected:
186 
189  std::string const &conf, char const *key,
190  int feature_id, bool const &def_value,
192 
193 public:
194 
201  int enable(int f, bool dry_run = false, bool toplevel = true);
202 
205  int disable(int f);
206 
210  void free_children_deps();
211 
213  void restore_children_deps();
214 
217  int decr_ref_count(int f);
218 
222  virtual void do_feature_side_effects(int /* id */) {}
223 
224  // NOTE that all feature enums should start with f_*_active
258  f_cvb_ntot
259  };
260 
339  f_cv_linear,
340  f_cv_homogeneous,
345  };
346 
387  };
388 
390  f_ag_active,
391  f_ag_center,
392  f_ag_center_origin,
393  f_ag_rotate,
394  f_ag_fitting_group,
397 // f_ag_min_msd_fit,
400  f_ag_fit_gradients,
401  f_ag_atom_forces,
402  f_ag_scalable,
403  f_ag_scalable_com,
406  f_ag_ntot
407  };
408 
410  virtual int init_dependencies() = 0;
411 
413  void require_feature_self(int f, int g);
414 
416  void exclude_feature_self(int f, int g);
417 
419  void require_feature_children(int f, int g);
420 
422  void require_feature_alt(int f, int g, int h);
423 
425  void require_feature_alt(int f, int g, int h, int i);
426 
428  void require_feature_alt(int f, int g, int h, int i, int j);
429 
431  void print_state();
432 
434  inline void check_enabled(int f, std::string const &reason) const
435  {
436  if (! is_enabled(f)) {
437  cvm::error("Error: "+reason+" requires that the feature \""+
438  features()[f]->description+"\" is active.\n", COLVARS_BUG_ERROR);
439  }
440  }
441 
442 };
443 
444 #endif
445 
446 
int disable(int f)
Definition: colvardeps.cpp:299
Colvar is awake (active on its own accord) this timestep.
Definition: colvardeps.h:265
Gradients are calculated and temporarily stored, so that external forces can be applied.
Definition: colvardeps.h:268
features_biases
Definition: colvardeps.h:225
Definition: colvardeps.h:99
Calculate total force from atomic forces.
Definition: colvardeps.h:280
std::vector< int > alternate_refs
Definition: colvardeps.h:68
This CVC provides a default value for the colvar&#39;s upper boundary.
Definition: colvardeps.h:359
features_atomgroup
Definition: colvardeps.h:389
whether this bias will compute a PMF
Definition: colvardeps.h:247
This CVC is a function of centers of mass.
Definition: colvardeps.h:378
int time_step_factor
Definition: colvardeps.h:77
void init_feature(int feature_id, const char *description, feature_type type)
Pair a numerical feature ID with a description and type.
Definition: colvardeps.cpp:388
bool enabled
Definition: colvardeps.h:55
Colvar is periodic.
Definition: colvardeps.h:334
void exclude_feature_self(int f, int g)
Make features f and g mutually exclusive within the same object.
Definition: colvardeps.cpp:401
force this bias to act on actual value for extended-Lagrangian coordinates
Definition: colvardeps.h:235
Calculate the velocity with finite differences.
Definition: colvardeps.h:275
void require_feature_children(int f, int g)
Make feature f require feature g within children.
Definition: colvardeps.cpp:407
Centers-of-mass used in this CVC can be computed in parallel.
Definition: colvardeps.h:382
void provide(int feature_id, bool truefalse=true)
Definition: colvardeps.cpp:93
Build list of atoms involved in CVC calculation.
Definition: colvardeps.h:384
bool available
Feature may be enabled, subject to possible dependencies.
Definition: colvardeps.h:51
Provide a discretization of the values of the colvar to be used by the biases or in analysis (needs l...
Definition: colvardeps.h:324
depends on simulation history
Definition: colvardeps.h:241
The total force for this CVC will be computed from one group only.
Definition: colvardeps.h:371
requires scalar colvars
Definition: colvardeps.h:245
Values of this CVC lie in a periodic interval.
Definition: colvardeps.h:353
Output the potential and kinetic energies (for extended Lagrangian colvars only)
Definition: colvardeps.h:300
The upper boundary is not defined from user&#39;s choice.
Definition: colvardeps.h:316
CVC calculates atom gradients.
Definition: colvardeps.h:363
An extended variable that sets an external variable in the back-end (eg. an alchemical coupling param...
Definition: colvardeps.h:295
The total force is calculated, projecting the atomic forces on the inverse gradient.
Definition: colvardeps.h:278
An upper boundary is defined.
Definition: colvardeps.h:312
A lower boundary is defined.
Definition: colvardeps.h:310
is scalar
Definition: colvardeps.h:338
CVC calculates the Jacobian term of the total-force expression.
Definition: colvardeps.h:369
Collective variables main module.
void free_children_deps()
Definition: colvardeps.cpp:43
void restore_children_deps()
re-enable children features (to be used when object becomes active)
Definition: colvardeps.cpp:73
Computation of this CVC is enabled.
Definition: colvardeps.h:349
Output the total force to the trajectory file.
Definition: colvardeps.h:308
The extended system coordinate undergoes Langevin dynamics.
Definition: colvardeps.h:297
Number of CVC features.
Definition: colvardeps.h:386
static int error(std::string const &message, int code=-1)
Print a message to the main log and set global error code.
Definition: colvarmodule.cpp:2025
CVC accesses atom groups directly (as opposed to going throuh other objects)
Definition: colvardeps.h:361
requires total forces
Definition: colvardeps.h:237
The variable has a harmonic restraint around a moving center with fictitious mass; bias forces will b...
Definition: colvardeps.h:291
int ref_count
Definition: colvardeps.h:63
std::vector< colvardeps * > children
Definition: colvardeps.h:158
Compute time correlation function.
Definition: colvardeps.h:328
depends on time
Definition: colvardeps.h:243
Subtract the applied force from the total force.
Definition: colvardeps.h:282
void require_feature_self(int f, int g)
Make feature f require feature g within the same object.
Definition: colvardeps.cpp:395
void check_enabled(int f, std::string const &reason) const
Check that a feature is enabled, raising COLVARS_BUG_ERROR if not.
Definition: colvardeps.h:434
Calculate colvar.
Definition: colvardeps.h:263
This CVC computes a scalar value.
Definition: colvardeps.h:351
multiple timestep through time_step_factor
Definition: colvardeps.h:342
This CVC can be computed in parallel.
Definition: colvardeps.h:380
Bias is awake (active on its own accord) this timestep.
Definition: colvardeps.h:229
Do not report the Jacobian force as part of the total force instead, apply a correction internally to...
Definition: colvardeps.h:287
This CVC provides a default value for the colvar&#39;s width.
Definition: colvardeps.h:355
Collect atomic gradient data from all cvcs into vector atomic_gradient.
Definition: colvardeps.h:271
Build list of atoms involved in CV calculation.
Definition: colvardeps.h:273
Bias is active.
Definition: colvardeps.h:227
Output the value to the trajectory file (on by default)
Definition: colvardeps.h:302
CVC calculates and stores inverse atom gradients (used for total force)
Definition: colvardeps.h:367
Alias for old default behavior (should be phased out)
Definition: colvarparse.h:72
whether this bias will write TI samples
Definition: colvardeps.h:251
std::vector< feature_state > feature_states
List of the states of all features.
Definition: colvardeps.h:80
features_colvar
Definition: colvardeps.h:261
Build list of atoms involved in atom group.
Definition: colvardeps.h:405
The colvar has only one component.
Definition: colvardeps.h:336
Value and gradient computed by user function through Lepton.
Definition: colvardeps.h:332
calc_gradients() will call debug_gradients() for every group needed
Definition: colvardeps.h:373
Parent class for a member object of a bias, cv or cvc etc. containing features and their dependencies...
Definition: colvardeps.h:34
void remove_all_children()
Definition: colvardeps.cpp:507
features_cvc
Definition: colvardeps.h:347
virtual void do_feature_side_effects(int)
Definition: colvardeps.h:222
whether this bias should write the TI PMF
Definition: colvardeps.h:253
whether this bias will compute TI samples
Definition: colvardeps.h:249
Estimate Jacobian derivative.
Definition: colvardeps.h:284
Output the applied force to the trajectory file.
Definition: colvardeps.h:306
Reflecting upper boundary condition.
Definition: colvardeps.h:320
whether this bias is applied to one or more ext-Lagrangian colvars
Definition: colvardeps.h:257
void set_enabled(int feature_id, bool truefalse=true)
Enable or disable, depending on flag value.
Definition: colvardeps.cpp:98
This contains the current state of each feature for each object.
Definition: colvardeps.h:46
Accumulates data starting from step 0 of a simulation run.
Definition: colvardeps.h:231
int decr_ref_count(int f)
Definition: colvardeps.cpp:362
Reflecting lower boundary condition.
Definition: colvardeps.h:318
Parse_Mode
How a keyword is parsed in a string.
Definition: colvarparse.h:53
Definition: colvardeps.h:376
Compute running average.
Definition: colvardeps.h:326
Parsing functions for collective variables.
int enable(int f, bool dry_run=false, bool toplevel=true)
Definition: colvardeps.cpp:125
whether this bias uses an external grid to scale the biasing forces
Definition: colvardeps.h:255
Base class containing parsing functions; all objects which need to parse input inherit from this...
Definition: colvarparse.h:27
will apply forces
Definition: colvardeps.h:233
int get_time_step_factor() const
returns time_step_factor
Definition: colvardeps.h:92
whether this bias should record the accumulated work
Definition: colvardeps.h:239
void print_state()
print all enabled features and those of children, for debugging
Definition: colvardeps.cpp:436
virtual int init_dependencies()=0
Initialize dependency tree for object of a derived class.
This CVC provides a default value for the colvar&#39;s lower boundary.
Definition: colvardeps.h:357
The lower boundary is not defined from user&#39;s choice.
Definition: colvardeps.h:314
feature_type
Enum of possible feature types.
Definition: colvardeps.h:83
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.
Definition: colvardeps.cpp:107
Output the velocity to the trajectory file.
Definition: colvardeps.h:304
void require_feature_alt(int f, int g, int h)
Make feature f require either g or h within the same object.
Definition: colvardeps.cpp:412
Does not have explicit atom gradients from parent CVC.
Definition: colvardeps.h:399
Number of colvar features.
Definition: colvardeps.h:344
CVC calculates and stores explicit atom gradients on rank 0.
Definition: colvardeps.h:365
feature_type type
Type of this feature, from the enum feature_type.
Definition: colvardeps.h:129
Value and gradient computed by user script.
Definition: colvardeps.h:330
std::vector< colvardeps * > parents
Definition: colvardeps.h:162