colvarmodule Class Reference

Collective variables module (main class) More...

#include <colvarmodule.h>

Collaboration diagram for colvarmodule:

Classes
class	atom
	Stores numeric id, mass and all mutable data for an atom, mostly used by a colvar::cvc. More...
class	atom_group
	Group of atom objects, mostly used by a colvar::cvc object to gather all atomic data. More...
class	matrix2d
	Arbitrary size array (two dimensions) suitable for linear algebra operations (i.e. for floating point numbers it can be used with library functions) More...
class	quaternion
	1-dimensional vector of real numbers with four components and a quaternion algebra More...
class	rmatrix
	2-dimensional array of real numbers with three components along each dimension (works with colvarmodule::rvector) More...
class	rotation
	A rotation between two sets of coordinates (for the moment a wrapper for colvarmodule::quaternion) More...
class	rvector
	vector of real numbers with three components More...
class	usage
	Track usage of Colvars features. More...
class	vector1d
	Arbitrary size array (one dimensions) suitable for linear algebra operations (i.e. for floating point numbers it can be used with library functions) More...

Public Types
typedef long long	step_number
	Use a 64-bit integer to store the step number.
typedef double	real
	Defining an abstract real number allows to switch precision.
typedef int	residue_id
	Residue identifier.
typedef rvector	atom_pos
	Atom position (different type name from rvector, to make possible future PBC-transparent implementations)
typedef std::vector< atom >::iterator	atom_iter
typedef std::vector< atom >::const_iterator	atom_const_iter

Public Member Functions
std::string	version () const
	Get the version string (YYYY-MM-DD format)
int	version_number () const
	Get the version number (higher = more recent)
int	patch_version_number () const
	Get the patch version number (non-zero in patch releases of other packages)
void	register_named_atom_group (atom_group *ag)
	Register a named atom group into named_atom_groups.
void	unregister_named_atom_group (atom_group *ag)
	Remove a named atom group from named_atom_groups.
std::vector< colvar * > *	variables ()
	Array of collective variables.
std::vector< colvar * > *	variables_active ()
	Collective variables with the active flag on.
std::vector< colvar * > *	variables_active_smp ()
std::vector< int > *	variables_active_smp_items ()
	Indexes of the items to calculate for each colvar.
std::vector< colvarbias * > *	biases_active ()
	Array of active collective variable biases.
size_t	size () const
	How many objects (variables and biases) are configured yet?
	colvarmodule (colvarproxy *proxy)
	~colvarmodule ()
	Destructor.
void	set_initial_step (step_number it)
	Set the initial step number (it is 0 otherwise); may be overridden when reading a state.
int	reset ()
	Actual function called by the destructor.
int	read_config_file (char const *config_file_name)
int	read_config_string (std::string const &conf)
	Parse a config string assuming it is a complete configuration (i.e. calling all parse functions)
int	parse_config (std::string &conf)
	Parse a "clean" config string (no comments)
std::string const &	get_config () const
	Get the configuration string read so far (includes comments)
int	parse_global_params (std::string const &conf)
	Parse the few module's global parameters.
int	parse_colvars (std::string const &conf)
	Parse and initialize collective variables.
int	run_tcl_script (std::string const &filename)
	Run provided Tcl script.
int	parse_biases (std::string const &conf)
	Parse and initialize collective variable biases. More...
int	append_new_config (std::string const &conf)
	Add new configuration during parsing (e.g. to implement back-compatibility); cannot be nested, i.e. conf should not contain anything that triggers another call.
void	config_changed ()
	Signals to the module object that the configuration has changed.
size_t	num_variables () const
	Return how many variables are defined.
size_t	num_variables_feature (int feature_id) const
	Return how many variables have this feature enabled.
size_t	num_biases () const
	Return how many biases are defined.
size_t	num_biases_feature (int feature_id) const
	Return how many biases have this feature enabled.
size_t	num_biases_type (std::string const &type) const
	Return how many biases of this type are defined.
std::vector< std::string > const	time_dependent_biases () const
int	update_engine_parameters ()
int	setup_input ()
	(Re)initialize and (re)read the input state file calling read_restart()
int	setup_output ()
	(Re)initialize the output trajectory and state file (does not write it yet)
std::istream &	read_state (std::istream &is)
	Read all objects' state fron a formatted (text) stream.
memory_stream &	read_state (memory_stream &is)
	Read all objects' state fron an unformatted (binary) stream.
int	set_input_state_buffer (size_t n, unsigned char *buf)
	Set an internal state buffer, to be read later as an unformatted stream when ready.
int	set_input_state_buffer (std::vector< unsigned char > &buf)
	Same as set_input_state_buffer() for C array, but uses std::move.
std::istream &	read_objects_state (std::istream &is)
	Read the states of individual objects; allows for changes.
memory_stream &	read_objects_state (memory_stream &is)
	Read the states of individual objects; allows for changes.
int	print_total_forces_errning (bool warn_total_forces)
	If needed (old restart file), print the warning that cannot be ignored.
std::ostream &	write_state (std::ostream &os)
	Write the state of the module to a formatted (text) file.
memory_stream &	write_state (memory_stream &os)
	Write the state of the module to an unformatted (binary) file.
int	write_state_buffer (std::vector< unsigned char > &buffer)
	Write the state of the module to an array of bytes (wrapped as a memory_stream object)
int	open_traj_file (std::string const &file_name)
	Open a trajectory file if requested (and leave it open)
int	close_traj_file ()
	Close it (note: currently unused)
std::ostream &	write_traj (std::ostream &os)
	Write in the trajectory file.
std::ostream &	write_traj_label (std::ostream &os)
	Write explanatory labels in the trajectory file.
int	write_traj_files ()
	Write all trajectory files.
int	write_restart_file (std::string const &out_name)
	Write a state file useful to resume the simulation.
int	write_output_files ()
	Write all other output files.
int	write_restart_string (std::string &output)
	Write the state into a string.
int	change_configuration (std::string const &bias_name, std::string const &conf)
std::string	read_colvar (std::string const &name)
	Read a colvar value.
real	energy_difference (std::string const &bias_name, std::string const &conf)
int	calc ()
	Main worker function.
int	calc_colvars ()
	Calculate collective variables.
int	calc_biases ()
	Calculate biases.
int	update_colvar_forces ()
	Integrate bias and restraint forces, send colvar forces to atoms.
int	analyze ()
	Perform analysis.
int	end_of_step ()
	Carry out operations needed before next step is run.
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)
int	cite_feature (std::string const &feature)
	Track usage of the given Colvars feature.
std::string	feature_report (int flag=0)
	Report usage of the Colvars features.
int	read_index_file (char const *filename)
	Read a Gromacs .ndx file.
int	reset_index_groups ()
	Clear the index groups loaded so far.
int	load_coords_xyz (char const *filename, std::vector< rvector > *pos, atom_group *atoms, bool keep_open=false)
	Load coordinates into an atom group from an XYZ file (assumes Angstroms)
std::string	restart_version () const
	Version of the most recent state file read.
int	restart_version_number () const
	Integer version of the most recent state file read.
int	calc_scripted_forces ()
	Calculate the energy and forces of scripted biases.

Static Public Member Functions
static real	integer_power (real const &x, int const n)
	Override the STL pow() with a product for n integer.
static real	pow (real const &x, real const &y)
	Reimplemented to work around MS compiler issues.
static real	floor (real const &x)
	Reimplemented to work around MS compiler issues.
static real	fabs (real const &x)
	Reimplemented to work around MS compiler issues.
static real	sqrt (real const &x)
	Reimplemented to work around MS compiler issues.
static real	sin (real const &x)
	Reimplemented to work around MS compiler issues.
static real	cos (real const &x)
	Reimplemented to work around MS compiler issues.
static real	asin (real const &x)
	Reimplemented to work around MS compiler issues.
static real	acos (real const &x)
	Reimplemented to work around MS compiler issues.
static real	atan2 (real const &x, real const &y)
	Reimplemented to work around MS compiler issues.
static real	exp (real const &x)
	Reimplemented to work around MS compiler issues.
static real	logn (real const &x)
static void	set_error_bits (int code)
static bool	get_error_bit (int code)
static int	get_error ()
static void	clear_error ()
static step_number	step_relative ()
	Return the current step number from the beginning of this run.
static step_number	step_absolute ()
static std::string &	output_prefix ()
	Accessor for the above.
static bool	debug ()
	Whether debug output should be enabled (compile-time option)
static std::istream &	getline (std::istream &is, std::string &line)
static std::string	state_file_prefix (char const *filename)
	Strips .colvars.state from filename and checks that it is not empty.
static int	backup_file (char const *filename)
	Backup a file before writing it.
static colvarbias *	bias_by_name (std::string const &name)
	Look up a bias by name; returns NULL if not found.
static colvar *	colvar_by_name (std::string const &name)
	Look up a colvar by name; returns NULL if not found.
static atom_group *	atom_group_by_name (std::string const &name)
	Look up a named atom group by name; returns NULL if not found.
static std::string	to_str (char const *s)
	Convert to string for output purposes.
static std::string	to_str (std::string const &s)
	Convert to string for output purposes.
static std::string	to_str (bool x)
	Convert to string for output purposes.
static std::string	to_str (int const &x, size_t width=0, size_t prec=0)
	Convert to string for output purposes.
static std::string	to_str (size_t const &x, size_t width=0, size_t prec=0)
	Convert to string for output purposes.
static std::string	to_str (long int const &x, size_t width=0, size_t prec=0)
	Convert to string for output purposes.
static std::string	to_str (step_number const &x, size_t width=0, size_t prec=0)
	Convert to string for output purposes.
static std::string	to_str (real const &x, size_t width=0, size_t prec=0)
	Convert to string for output purposes.
static std::string	to_str (rvector const &x, size_t width=0, size_t prec=0)
	Convert to string for output purposes.
static std::string	to_str (quaternion const &x, size_t width=0, size_t prec=0)
	Convert to string for output purposes.
static std::string	to_str (colvarvalue const &x, size_t width=0, size_t prec=0)
	Convert to string for output purposes.
static std::string	to_str (vector1d< real > const &x, size_t width=0, size_t prec=0)
	Convert to string for output purposes.
static std::string	to_str (matrix2d< real > const &x, size_t width=0, size_t prec=0)
	Convert to string for output purposes.
static std::string	to_str (std::vector< int > const &x, size_t width=0, size_t prec=0)
	Convert to string for output purposes.
static std::string	to_str (std::vector< size_t > const &x, size_t width=0, size_t prec=0)
	Convert to string for output purposes.
static std::string	to_str (std::vector< long int > const &x, size_t width=0, size_t prec=0)
	Convert to string for output purposes.
static std::string	to_str (std::vector< real > const &x, size_t width=0, size_t prec=0)
	Convert to string for output purposes.
static std::string	to_str (std::vector< rvector > const &x, size_t width=0, size_t prec=0)
	Convert to string for output purposes.
static std::string	to_str (std::vector< quaternion > const &x, size_t width=0, size_t prec=0)
	Convert to string for output purposes.
static std::string	to_str (std::vector< colvarvalue > const &x, size_t width=0, size_t prec=0)
	Convert to string for output purposes.
static std::string	to_str (std::vector< std::string > const &x, size_t width=0, size_t prec=0)
	Convert to string for output purposes.
static std::string	wrap_string (std::string const &s, size_t nchars)
	Reduce the number of characters in a string.
static real	dt ()
	Time step of MD integrator (fs)
static void	request_total_force ()
	Request calculation of total force from MD engine.
static void	log (std::string const &message, int min_log_level=10)
static int	error (std::string const &message, int code=-1)
	Print a message to the main log and set global error code.
static int	log_level ()
	Level of logging requested by the user.
static int	log_init_messages ()
	Level at which initialization messages are logged.
static int	log_user_params ()
	Level at which a keyword's user-provided value is logged.
static int	log_default_params ()
	Level at which a keyword's default value is logged.
static int	log_output_files ()
	Level at which output-file operations are logged.
static int	log_input_files ()
	Level at which input-file operations (configuration, state) are logged.
static rvector	position_distance (atom_pos const &pos1, atom_pos const &pos2)
	Get the distance between two atomic positions with pbcs handled correctly.
static int	load_coords (char const *filename, std::vector< rvector > *pos, atom_group *atoms, std::string const &pdb_field, double pdb_field_value=0.0)
	Load coordinates for a group of atoms from a file (PDB or XYZ); if "pos" is already allocated, the number of its elements must match the number of entries in "filename". More...
static real	rand_gaussian ()
	Pseudo-random number with Gaussian distribution.
static size_t &	depth ()
	Get the current object depth in the hierarchy.
static void	increase_depth ()
	Increase the depth (number of indentations in the output)
static void	decrease_depth ()
	Decrease the depth (number of indentations in the output)
static bool	scripted_forces ()
static colvarmodule *	main ()
	Access the one instance of the Colvars module.

Public Attributes
bool	binary_restart
std::vector< colvarbias * >	biases
	Array of collective variable biases.
real	total_bias_energy
	Energy of built-in and scripted biases, summed per time-step.
std::vector< std::string >	index_file_names
	Names of .ndx files that have been loaded.
std::vector< std::string >	index_group_names
	Names of groups from one or more Gromacs .ndx files.
std::vector< std::vector< int > * >	index_groups
	Groups from one or more Gromacs .ndx files.
std::string	restart_out_name
	Output restart file name.

Static Public Attributes
static step_number	it = 0
	Current step number.
static step_number	it_restart = 0
	Starting step number for this run.
static real	debug_gradients_step_size = 1.0e-07
	Finite difference step size (if there is no dynamics, or if gradients need to be tested independently from the size of dt)
static size_t const	it_width = 12
	Number of characters to represent a time step.
static size_t const	cv_prec = 14
	Number of digits to represent a collective variables value(s)
static size_t const	cv_width = 21
	Number of characters to represent a collective variables value(s)
static size_t const	en_prec = 14
	Number of digits to represent the collective variables energy.
static size_t const	en_width = 21
	Number of characters to represent the collective variables energy.
static const char *const	line_marker
	Line separator in the log output. More...
static size_t	cv_traj_freq = 0
	Frequency for collective variables trajectory output.
static size_t	restart_out_freq = 0
	Frequency for saving output restarts.
static bool	use_scripted_forces = false
	Use scripted colvars forces?
static bool	scripting_after_biases = true
	Wait for all biases before calculating scripted forces?
static colvarproxy *	proxy = NULL
	Pointer to the proxy object, used to retrieve atomic data from the hosting program; it is static in order to be accessible from static functions in the colvarmodule class.

Protected Attributes
colvarparse *	parse
	Configuration file parser object.
std::string	cv_traj_name
	Name of the trajectory file.
bool	cv_traj_write_labels
	Write labels at the next iteration.
std::string	restart_version_str
	Version of the most recent state file read.
int	restart_version_int
	Integer version of the most recent state file read.
size_t	depth_s
	Counter for the current depth in the object hierarchy (useg e.g. in output)
std::vector< size_t >	depth_v
	Thread-specific depth.
int	xyz_reader_use_count
	Track how many times the XYZ reader has been used.
usage *	usage_
	Track usage of Colvars features.

Private Member Functions
	colvarmodule ()
	Cannot initialize the main object without a proxy.
template<class bias_type >
int	parse_biases_type (std::string const &conf, char const *keyword)
	Parse and initialize collective variable biases of a specific type.
bool	check_new_bias (std::string &conf, char const *key)
int	catch_input_errors (int result)
	Useful wrapper to interrupt parsing if any error occurs.
template<typename IST >
IST &	read_state_template_ (IST &is)
template<typename OST >
OST &	write_state_template_ (OST &os)

Private Attributes
int	version_int = 0
	Integer representing the version string (allows comparisons)
int	patch_version_int = 0
	Patch version number (non-zero in patch releases of other packages)
std::string	cvm_output_prefix
	Prefix for all output files for this run.
std::vector< colvar * >	colvars
	Array of collective variables.
std::vector< colvar * >	colvars_active
	Array of collective variables.
std::vector< colvar * >	colvars_smp
std::vector< int >	colvars_smp_items
	Indexes of the items to calculate for each colvar.
std::vector< atom_group * >	named_atom_groups
	Array of named atom groups.
void *	num_biases_types_used_
	Pointer to a map counting how many biases of each type were used.
std::vector< colvarbias * >	biases_active_
	Array of active collective variable biases.
std::string	config_string
	Configuration string read so far by the module (includes comments)
std::string	extra_conf
std::string	source_Tcl_script
	Initialization Tcl script, user-provided.
std::string	default_input_state_file_
	Default input state file; if given, it is read unless the MD engine provides it.
std::vector< unsigned char >	input_state_buffer_
	Internal state buffer, to be read as an unformatted stream.

Static Private Attributes
static int	errorCode = 0
static int	log_level_ = 10
	Level of logging requested by the user.

Detailed Description

Collective variables module (main class)

Class to control the collective variables calculation. An object (usually one) of this class is spawned from the MD program, containing all i/o routines and general interface.

At initialization, the colvarmodule object creates a proxy object to provide a transparent interface between the MD program and the child objects

Constructor & Destructor Documentation

colvarmodule()

colvarmodule::colvarmodule

(

colvarproxy *

proxy

)

Constructor

Parameters

Pointer

to instance of the proxy class (communicate with engine)

Member Function Documentation

change_configuration()

int colvarmodule::change_configuration	(	std::string const &	bias_name,
		std::string const &	conf
	)

Load new configuration for the given bias - currently works for harmonic (force constant and/or centers)

check_new_bias()

bool colvarmodule::check_new_bias ( std::string &  conf, char const *  key  )

private

Test error condition and keyword parsing on error, delete new bias

energy_difference()

cvm::real colvarmodule::energy_difference	(	std::string const &	bias_name,
		std::string const &	conf
	)

Calculate change in energy from using alt. config. for the given bias - currently works for harmonic (force constant and/or centers)

getline()

std::istream & colvarmodule::getline ( std::istream &  is, std::string &  line  )

static

Allow reading from Windows text files using using std::getline (which can still be used when the text is produced by Colvars itself)

load_coords()

static int colvarmodule::load_coords ( char const *  filename, std::vector< rvector > *  pos, atom_group *  atoms, std::string const &  pdb_field, double  pdb_field_value = 0.0  )

static

Load coordinates for a group of atoms from a file (PDB or XYZ); if "pos" is already allocated, the number of its elements must match the number of entries in "filename".

Parameters

filename	name of the file
pos	array of coordinates
atoms	group containing the atoms (used to obtain internal IDs)
pdb_field	(optional) if the file is a PDB and this string is non-empty, select atoms for which this field is non-zero
pdb_field_value	(optional) if non-zero, select only atoms whose pdb_field equals this

log()

void colvarmodule::log ( std::string const &  message, int  min_log_level = 10  )

static

Print a message to the main log

Parameters

message	Message to print
min_log_level	Only print if cvm::log_level() >= min_log_level

logn()

static real colvarmodule::logn ( real const &  x )

inlinestatic

Reimplemented to work around MS compiler issues. Note: log() is currently defined as the text logging function, but this can be changed at a later time

parse_biases()

int colvarmodule::parse_biases

(

std::string const &

conf

)

Parse and initialize collective variable biases.

initialize ABF instances

initialize ABMD instances

initialize adaptive linear biases

initialize harmonic restraints

initialize harmonic walls restraints

initialize histograms

initialize histogram restraints

initialize linear restraints

initialize metadynamics instances

initialize reweightaMD instances

initialize OPES instances

read_config_file()

int colvarmodule::read_config_file

(

char const *

config_file_name

)

Open a config file, load its contents, and pass it to config_string()

Parameters

config_file_name

Configuration file name

step_absolute()

static step_number colvarmodule::step_absolute ( )

inlinestatic

Return the current step number from the beginning of the whole calculation

time_dependent_biases()

std::vector< std::string > const colvarmodule::time_dependent_biases

(

)

const

Return the names of time-dependent biases with forces enabled (ABF, metadynamics, etc)

update_engine_parameters()

int colvarmodule::update_engine_parameters

(

)

(Re)initialize any internal data affected by changes in the engine Also calls setup() member functions of colvars and biases

variables_active_smp()

std::vector< colvar * > * colvarmodule::variables_active_smp

(

)

Collective variables to be calculated on different threads; colvars with multple items (e.g. multiple active CVCs) are duplicated

Member Data Documentation

colvars_smp

std::vector<colvar *> colvarmodule::colvars_smp

private

Collective variables to be calculated on different threads; colvars with multple items (e.g. multiple active CVCs) are duplicated

errorCode

int colvarmodule::errorCode = 0

staticprivate

Module-wide error state see constants at the top of this file

extra_conf

std::string colvarmodule::extra_conf

private

Auto-generated configuration during parsing (e.g. to implement back-compatibility)

line_marker

const char *const colvarmodule::line_marker

static

Initial value:

= (const char *)
  "----------------------------------------------------------------------\n"

Line separator in the log output.

---

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

• colvarmodule.h
• colvarmodule.cpp