colvardeps Class Reference

Parent class for a member object of a bias, cv or cvc etc. containing features and their dependencies, and handling dependency resolution. More...

#include <colvardeps.h>

Inheritance diagram for colvardeps:

Classes
class	feature
struct	feature_state
	This contains the current state of each feature for each object. More...

Public Types
enum	features_biases {   f_cvb_active , f_cvb_awake , f_cvb_step_zero_data , f_cvb_apply_force ,   f_cvb_bypass_ext_lagrangian , f_cvb_get_total_force , f_cvb_output_acc_work , f_cvb_history_dependent ,   f_cvb_time_dependent , f_cvb_scalar_variables , f_cvb_calc_pmf , f_cvb_calc_ti_samples ,   f_cvb_write_ti_samples , f_cvb_write_ti_pmf , f_cvb_scale_biasing_force , f_cvb_extended ,   f_cvb_ntot }
enum	features_colvar {   f_cv_active , f_cv_awake , f_cv_apply_force , f_cv_gradient ,   f_cv_collect_gradient , f_cv_collect_atom_ids , f_cv_fdiff_velocity , f_cv_total_force ,   f_cv_total_force_calc , f_cv_total_force_current_step , f_cv_subtract_applied_force , f_cv_Jacobian ,   f_cv_hide_Jacobian , f_cv_extended_Lagrangian , f_cv_external , 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_hard_lower_boundary ,   f_cv_hard_upper_boundary , f_cv_reflecting_lower_boundary , f_cv_reflecting_upper_boundary , f_cv_grid ,   f_cv_runave , f_cv_corrfunc , f_cv_scripted , f_cv_custom_function ,   f_cv_periodic , f_cv_single_cvc , f_cv_scalar , f_cv_linear ,   f_cv_homogeneous , f_cv_multiple_ts , f_cv_ntot }
enum	features_cvc {   f_cvc_active , f_cvc_scalar , f_cvc_periodic , f_cvc_width ,   f_cvc_lower_boundary , f_cvc_upper_boundary , f_cvc_explicit_atom_groups , f_cvc_gradient ,   f_cvc_explicit_gradient , f_cvc_inv_gradient , f_cvc_Jacobian , f_cvc_one_site_total_force ,   f_cvc_debug_gradient , f_cvc_pbc_minimum_image , f_cvc_com_based , f_cvc_scalable ,   f_cvc_scalable_com , f_cvc_collect_atom_ids , f_cvc_ntot }
enum	features_atomgroup {   f_ag_active , f_ag_center , f_ag_center_origin , f_ag_rotate ,   f_ag_fitting_group , f_ag_explicit_gradient , f_ag_fit_gradients , f_ag_atom_forces ,   f_ag_scalable , f_ag_scalable_com , f_ag_collect_atom_ids , f_ag_ntot }

Public Member Functions
int	get_time_step_factor () const
	returns time_step_factor
void	init_feature (int feature_id, const char *description, feature_type type)
	Pair a numerical feature ID with a description and type.
bool	is_not_set (int id)
bool	is_dynamic (int id)
bool	is_static (int id)
bool	is_user (int id)
virtual const std::vector< feature * > &	features () const =0
virtual std::vector< feature * > &	modify_features ()=0
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)
	Enable or disable, depending on flag value.
int	enable (int f, bool dry_run=false, bool toplevel=true, bool error=false)
int	disable (int f)
void	free_children_deps ()
void	restore_children_deps ()
	re-enable children features (to be used when object becomes active)
int	decr_ref_count (int f)
virtual void	do_feature_side_effects (int)
virtual int	init_dependencies ()=0
	Initialize dependency tree for object of a derived class. More...
void	require_feature_self (int f, int g)
	Make feature f require feature g within the same object.
void	exclude_feature_self (int f, int g)
	Make features f and g mutually exclusive within the same object.
void	require_feature_children (int f, int g)
	Make feature f require feature g within children.
void	require_feature_alt (int f, int g, int h)
	Make feature f require either g or h within the same object.
void	require_feature_alt (int f, int g, int h, int i)
	Make feature f require any of g, h, or i within the same object.
void	require_feature_alt (int f, int g, int h, int i, int j)
	Make feature f require any of g, h, i, or j within the same object.
void	print_state ()
	print all enabled features and those of children, for debugging
void	check_enabled (int f, std::string const &reason) const
	Check that a feature is enabled, raising COLVARS_BUG_ERROR if not.

Public Attributes
std::string	description

Protected Types
enum	feature_type { f_type_not_set , f_type_dynamic , f_type_user , f_type_static }
	Enum of possible feature types.

Protected Member Functions
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.

Protected Attributes
int	time_step_factor
std::vector< feature_state >	feature_states
	List of the states of all features.

Private Attributes
std::vector< colvardeps * >	children
std::vector< colvardeps * >	parents

Detailed Description

Parent class for a member object of a bias, cv or cvc etc. containing features and their dependencies, and handling dependency resolution.

There are 3 kinds of features:

1. Dynamic features are under the control of the dependency resolution system. They may be enabled or disabled depending on dependencies.
2. User features may be enabled based on user input (they may trigger a failure upon dependency resolution, though)
3. Static features are static properties of the object, determined programmatically at initialization time.

The following diagram summarizes the dependency tree at the bias, colvar, and colvarcomp levels. Isolated and atom group features are not shown to save space.

In all classes, feature 0 is active. When an object is inactivated all its children dependencies are dereferenced (free_children_deps) While the object is inactive, no dependency solving is done on children it is done when the object is activated back (restore_children_deps)

Member Enumeration Documentation

features_atomgroup

enum colvardeps::features_atomgroup

Enumerator
f_ag_explicit_gradient	Does not have explicit atom gradients from parent CVC. Perform a standard minimum msd fit for given atoms ie. not using refpositionsgroup
f_ag_collect_atom_ids	Build list of atoms involved in atom group.

features_biases

enum colvardeps::features_biases

Enumerator
f_cvb_active	Bias is active.
f_cvb_awake	Bias is awake (active on its own accord) this timestep.
f_cvb_step_zero_data	Accumulates data starting from step 0 of a simulation run.
f_cvb_apply_force	will apply forces
f_cvb_bypass_ext_lagrangian	force this bias to act on actual value for extended-Lagrangian coordinates
f_cvb_get_total_force	requires total forces
f_cvb_output_acc_work	whether this bias should record the accumulated work
f_cvb_history_dependent	depends on simulation history
f_cvb_time_dependent	depends on time
f_cvb_scalar_variables	requires scalar colvars
f_cvb_calc_pmf	whether this bias will compute a PMF
f_cvb_calc_ti_samples	whether this bias will compute TI samples
f_cvb_write_ti_samples	whether this bias will write TI samples
f_cvb_write_ti_pmf	whether this bias should write the TI PMF
f_cvb_scale_biasing_force	whether this bias uses an external grid to scale the biasing forces
f_cvb_extended	whether this bias is applied to one or more ext-Lagrangian colvars

features_colvar

enum colvardeps::features_colvar

Enumerator
f_cv_active	Calculate colvar.
f_cv_awake	Colvar is awake (active on its own accord) this timestep.
f_cv_apply_force	External force can be applied, either to atoms or to an extended DOF.
f_cv_gradient	Gradients are calculated and temporarily stored, so that external forces can be propagated to atoms.
f_cv_collect_gradient	Collect atomic gradient data from all cvcs into vector atomic_gradient.
f_cv_collect_atom_ids	Build list of atoms involved in CV calculation.
f_cv_fdiff_velocity	Calculate the velocity with finite differences.
f_cv_total_force	The total force is calculated, projecting the atomic forces on the inverse gradient.
f_cv_total_force_calc	Calculate total force from atomic forces or get it from the back-end for an external parameter.
f_cv_total_force_current_step	Total force is that of current time step.
f_cv_subtract_applied_force	Subtract the applied force from the total force.
f_cv_Jacobian	Estimate Jacobian derivative.
f_cv_hide_Jacobian	Do not report the Jacobian force as part of the total force instead, apply a correction internally to cancel it.
f_cv_extended_Lagrangian	The variable has a harmonic restraint around a moving center with fictitious mass; bias forces will be applied to the center.
f_cv_external	A variable that constrains or follows an external parameter in the back-end (eg. an alchemical coupling parameter for lambda-dynamics) If extended Lagrangian, then we drive the external parameter Otherwise we follow it Can have a single component.
f_cv_Langevin	The extended system coordinate undergoes Langevin dynamics.
f_cv_output_energy	Output the potential and kinetic energies (for extended Lagrangian colvars only)
f_cv_output_value	Output the value to the trajectory file (on by default)
f_cv_output_velocity	Output the velocity to the trajectory file.
f_cv_output_applied_force	Output the applied force to the trajectory file.
f_cv_output_total_force	Output the total force to the trajectory file.
f_cv_lower_boundary	A lower boundary is defined.
f_cv_upper_boundary	An upper boundary is defined.
f_cv_hard_lower_boundary	The lower boundary is not defined from user's choice.
f_cv_hard_upper_boundary	The upper boundary is not defined from user's choice.
f_cv_reflecting_lower_boundary	Reflecting lower boundary condition.
f_cv_reflecting_upper_boundary	Reflecting upper boundary condition.
f_cv_grid	Provide a discretization of the values of the colvar to be used by the biases or in analysis (needs lower and upper boundary)
f_cv_runave	Compute running average.
f_cv_corrfunc	Compute time correlation function.
f_cv_scripted	Value and gradient computed by user script.
f_cv_custom_function	Value and gradient computed by user function through Lepton.
f_cv_periodic	Colvar is periodic.
f_cv_single_cvc	The colvar has only one component.
f_cv_scalar	is scalar
f_cv_multiple_ts	multiple timestep through time_step_factor
f_cv_ntot	Number of colvar features.

features_cvc

enum colvardeps::features_cvc

Enumerator
f_cvc_active	Computation of this CVC is enabled.
f_cvc_scalar	This CVC computes a scalar value.
f_cvc_periodic	Values of this CVC lie in a periodic interval.
f_cvc_width	This CVC provides a default value for the colvar's width.
f_cvc_lower_boundary	This CVC provides a default value for the colvar's lower boundary.
f_cvc_upper_boundary	This CVC provides a default value for the colvar's upper boundary.
f_cvc_explicit_atom_groups	CVC accesses atom groups directly (as opposed to going throuh other objects)
f_cvc_gradient	CVC calculates atom gradients.
f_cvc_explicit_gradient	CVC calculates and stores explicit atom gradients on rank 0.
f_cvc_inv_gradient	CVC calculates and stores inverse atom gradients (used for total force)
f_cvc_Jacobian	CVC calculates the Jacobian term of the total-force expression.
f_cvc_one_site_total_force	The total force for this CVC will be computed from one group only.
f_cvc_debug_gradient	calc_gradients() will call debug_gradients() for every group needed
f_cvc_pbc_minimum_image	With PBCs, minimum-image convention will be used for distances (does not affect the periodicity of CVC values, e.g. angles)
f_cvc_com_based	This CVC is a function of centers of mass.
f_cvc_scalable	This CVC can be computed in parallel.
f_cvc_scalable_com	Centers-of-mass used in this CVC can be computed in parallel.
f_cvc_collect_atom_ids	Build list of atoms involved in CVC calculation.
f_cvc_ntot	Number of CVC features.

Member Function Documentation

decr_ref_count()

int colvardeps::decr_ref_count

(

int

f

)

Decrement the reference count of a feature disabling it if it's dynamic and count reaches zero

disable()

int colvardeps::disable

(

int

f

)

Disable a feature, decrease the reference count of its dependencies and recursively disable them as applicable

do_feature_side_effects()

virtual void colvardeps::do_feature_side_effects ( int  )

inlinevirtual

Implements possible actions to be carried out when a given feature is enabled Base function does nothing, can be overloaded

Reimplemented in colvar, and colvarmodule::atom_group.

enable()

int colvardeps::enable	(	int	f,
		bool	dry_run = false,
		bool	toplevel = true,
		bool	error = false
	)

Enable a feature and recursively solve its dependencies. For accurate reference counting, do not add spurious calls to enable()

Parameters

dry_run	Recursively test whether a feature is available, without enabling it
toplevel	False if this is called as part of a chain of dependency resolution. This is used to diagnose failed dependencies by displaying the full stack: only the toplevel dependency will throw a fatal error.
error	Recursively enable, printing error messages along the way Necessary when propagating errors across alternate dependencies

features()

virtual const std::vector< feature * > & colvardeps::features ( ) const

pure virtual

Implemented in colvar, colvarbias, colvar::cvc, and colvarmodule::atom_group.

free_children_deps()

void colvardeps::free_children_deps

(

)

disable all enabled features to free their dependencies to be done when deleting the object Cannot be in the base class destructor because it needs the derived class features()

init_dependencies()

virtual int colvardeps::init_dependencies ( )

pure virtual

Initialize dependency tree for object of a derived class.

Implemented in colvar, colvarbias, colvar::cvc, and colvarmodule::atom_group.

provide()

void colvardeps::provide	(	int	feature_id,
		bool	truefalse = true
	)

Set the feature's available flag, without checking To be used for dynamic properties dependencies will be checked by enable()

remove_all_children()

void colvardeps::remove_all_children

(

)

Used before deleting an object, if not handled by that object's destructor (useful for cvcs because their children are member objects)

Member Data Documentation

children

std::vector<colvardeps *> colvardeps::children

private

pointers to objects this object depends on list should be maintained by any code that modifies the object this could be secured by making lists of colvars / cvcs / atom groups private and modified through accessor functions

parents

std::vector<colvardeps *> colvardeps::parents

private

pointers to objects that depend on this object the size of this array is in effect a reference counter

time_step_factor

int colvardeps::time_step_factor

protected

Time step multiplier (for coarse-timestep biases & colvars) Biases and colvars will only be calculated at those times (f_cvb_awake and f_cv_awake); a Biases use this to apply "impulse" biasing forces at the outer timestep Unused by lower-level objects (cvcs and atom groups)

---

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

• colvardeps.h
• colvardeps.cpp