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

Interface between the collective variables module and the simulation or analysis program (NAMD, VMD, LAMMPS...). This is the base class: each interfaced program is supported by a derived class. Only pure virtual functions ("= 0") must be reimplemented to ensure baseline functionality. More...

#include <colvarproxy.h>

Inheritance diagram for colvarproxy:
Inheritance graph
[legend]
Collaboration diagram for colvarproxy:
Collaboration graph
[legend]

Public Member Functions

 colvarproxy ()
 Constructor.
 
virtual ~colvarproxy ()
 Destructor.
 
virtual int setup ()
 (Re)initialize required member data after construction
 
virtual int update_input ()
 Update data required by the colvars module (e.g. cache atom positions) More...
 
virtual int update_output ()
 Update data based from the results of a module update (e.g. send forces)
 
virtual cvm::real unit_angstrom ()=0
 Value of the unit for atomic coordinates with respect to angstroms (used by some variables for hard-coded default values)
 
virtual cvm::real boltzmann ()=0
 Boltzmann constant.
 
virtual cvm::real temperature ()=0
 Temperature of the simulation (K)
 
virtual cvm::real dt ()=0
 Time step of the simulation (fs)
 
virtual cvm::real rand_gaussian (void)=0
 Pseudo-random number with Gaussian distribution.
 
virtual int get_frame (long int &)
 Get the current frame number.
 
virtual int set_frame (long int)
 Set the current frame number (as well as colvarmodule::it)
 
std::string & input_prefix ()
 
std::string restart_output_prefix ()
 Prefix to be used for output restart files.
 
std::string output_prefix ()
 Prefix to be used for output files (final system configuration)
 
virtual size_t restart_frequency ()
 Restarts will be written each time this number of steps has passed.
 
virtual bool simulation_running () const
 Whether a simulation is running (and try to prevent irrecovarable errors)
 
virtual int smp_enabled ()
 Whether threaded parallelization is available (TODO: make this a cvm::deps feature)
 
virtual int smp_colvars_loop ()
 Distribute calculation of colvars (and their components) across threads.
 
virtual int smp_biases_loop ()
 Distribute calculation of biases across threads.
 
virtual int smp_biases_script_loop ()
 Distribute calculation of biases across threads 2nd through last, with all scripted biased on 1st thread.
 
virtual int smp_thread_id ()
 Index of this thread.
 
virtual int smp_num_threads ()
 Number of threads sharing this address space.
 
virtual int smp_lock ()
 Lock the proxy's shared data for access by a thread, if threads are implemented; if not implemented, does nothing.
 
virtual int smp_trylock ()
 Attempt to lock the proxy's shared data.
 
virtual int smp_unlock ()
 Release the lock.
 
virtual bool replica_enabled ()
 Indicate if multi-replica support is available and active.
 
virtual int replica_index ()
 Index of this replica.
 
virtual int replica_num ()
 Total number of replica.
 
virtual void replica_comm_barrier ()
 Synchronize replica.
 
virtual int replica_comm_recv (char *msg_data, int buf_len, int src_rep)
 Receive data from other replica.
 
virtual int replica_comm_send (char *msg_data, int msg_len, int dest_rep)
 Send data to other replica.
 
virtual int run_force_callback ()
 Run a user-defined colvar forces script.
 
virtual int run_colvar_callback (std::string const &name, std::vector< const colvarvalue * > const &cvcs, colvarvalue &value)
 
virtual int run_colvar_gradient_callback (std::string const &name, std::vector< const colvarvalue * > const &cvcs, std::vector< cvm::matrix2d< cvm::real > > &gradient)
 
virtual void log (std::string const &message)=0
 Print a message to the main log.
 
virtual void error (std::string const &message)=0
 Print a message to the main log and let the rest of the program handle the error.
 
virtual void fatal_error (std::string const &message)=0
 Print a message to the main log and exit with error code.
 
virtual void exit (std::string const &message)
 Print a message to the main log and exit normally.
 
virtual std::ostream * output_stream (std::string const &output_name)
 Returns a reference to the given output channel; if this is not open already, then open it.
 
virtual int close_output_stream (std::string const &output_name)
 Closes the given output channel.
 
virtual int backup_file (char const *filename)
 Rename the given file, before overwriting it.
 
virtual void add_energy (cvm::real energy)=0
 Pass restraint energy value for current timestep to MD engine.
 
virtual void request_total_force (bool yesno)
 Tell the proxy whether total forces are needed (may not always be available)
 
virtual bool total_forces_enabled () const
 Are total forces being used?
 
virtual cvm::rvector position_distance (cvm::atom_pos const &pos1, cvm::atom_pos const &pos2)=0
 Get the PBC-aware distance vector between two positions.
 
virtual cvm::real position_dist2 (cvm::atom_pos const &pos1, cvm::atom_pos const &pos2)
 Get the PBC-aware square distance between two positions; may need to be reimplemented independently from position_distance() for optimization purposes.
 
virtual void select_closest_image (cvm::atom_pos &pos, cvm::atom_pos const &ref_pos)
 Get the closest periodic image to a reference position. More...
 
void select_closest_images (std::vector< cvm::atom_pos > &pos, cvm::atom_pos const &ref_pos)
 Perform select_closest_image() on a set of atomic positions. More...
 
virtual int init_atom (int atom_number)=0
 Prepare this atom for collective variables calculation, selecting it by numeric index (1-based)
 
virtual int check_atom_id (int atom_number)=0
 Check that this atom number is valid, but do not initialize the corresponding atom yet.
 
virtual int init_atom (cvm::residue_id const &residue, std::string const &atom_name, std::string const &segment_id)
 
virtual int check_atom_id (cvm::residue_id const &residue, std::string const &atom_name, std::string const &segment_id)
 Check that this atom is valid, but do not initialize it yet.
 
virtual void clear_atom (int index)
 Used by the atom class destructor: rather than deleting the array slot (costly) set the corresponding atoms_ncopies to zero.
 
int get_atom_id (int index) const
 Get the numeric ID of the given atom (for the program)
 
cvm::real get_atom_mass (int index) const
 Get the mass of the given atom.
 
cvm::real get_atom_charge (int index) const
 Get the charge of the given atom.
 
cvm::rvector get_atom_position (int index) const
 Read the current position of the given atom.
 
cvm::rvector get_atom_total_force (int index) const
 Read the current total force of the given atom.
 
void apply_atom_force (int index, cvm::rvector const &new_force)
 Request that this force is applied to the given atom.
 
virtual cvm::rvector get_atom_velocity (int index)
 Read the current velocity of the given atom.
 
std::vector< int > * modify_atom_ids ()
 
std::vector< cvm::real > * modify_atom_masses ()
 
std::vector< cvm::real > * modify_atom_charges ()
 
std::vector< cvm::rvector > * modify_atom_positions ()
 
std::vector< cvm::rvector > * modify_atom_total_forces ()
 
std::vector< cvm::rvector > * modify_atom_new_colvar_forces ()
 
virtual int load_atoms (char const *filename, cvm::atom_group &atoms, std::string const &pdb_field, double const pdb_field_value=0.0)
 Read atom identifiers from a file. More...
 
virtual int load_coords (char const *filename, std::vector< cvm::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 (usually a PDB); if "pos" is already allocated, the number of its elements must match the number of atoms in "filename".
 
virtual int scalable_group_coms ()
 TODO Add here containers of handles to cvc objects that are computed in parallel. More...
 
int add_atom_group_slot (int atom_group_id)
 Used by all init_atom_group() functions: create a slot for an atom group not requested yet.
 
virtual int init_atom_group (std::vector< int > const &atoms_ids)
 Prepare this group for collective variables calculation, selecting atoms by internal ids (0-based)
 
virtual void clear_atom_group (int index)
 Used by the atom_group class destructor.
 
cvm::real get_atom_group_id (int index) const
 Get the numeric ID of the given atom group (for the MD program)
 
cvm::real get_atom_group_mass (int index) const
 Get the mass of the given atom group.
 
cvm::real get_atom_group_charge (int index) const
 Get the charge of the given atom group.
 
cvm::rvector get_atom_group_com (int index) const
 Read the current position of the center of mass given atom group.
 
cvm::rvector get_atom_group_total_force (int index) const
 Read the current total force of the given atom group.
 
void apply_atom_group_force (int index, cvm::rvector const &new_force)
 Request that this force is applied to the given atom group.
 
virtual cvm::rvector get_atom_group_velocity (int index)
 Read the current velocity of the given atom group.
 

Public Attributes

colvarmodulecolvars
 Pointer to the main object.
 
std::string input_prefix_str
 Prefix to be used for input files (restarts, not configuration)
 
std::string output_prefix_str
 
std::string restart_output_prefix_str
 
bool b_smp_active
 Whether threaded parallelization should be used (TODO: make this a cvm::deps feature)
 
colvarscriptscript
 
bool force_script_defined
 is a user force script defined?
 
bool have_scripts
 Do we have a scripting interface?
 

Protected Member Functions

int add_atom_slot (int atom_id)
 Used by all init_atom() functions: create a slot for an atom not requested yet.
 

Protected Attributes

bool b_simulation_running
 Whether a simulation is running (and try to prevent irrecovarable errors)
 
std::list< std::ostream * > output_files
 Currently opened output files: by default, these are ofstream objects. Allows redefinition to implement different output mechanisms.
 
std::list< std::string > output_stream_names
 Identifiers for output_stream objects: by default, these are the names of the files.
 
std::vector< int > atoms_ids
 Array of 0-based integers used to uniquely associate atoms within the host program.
 
std::vector< size_t > atoms_ncopies
 Keep track of how many times each atom is used by a separate colvar object.
 
std::vector< cvm::realatoms_masses
 Masses of the atoms (allow redefinition during a run, as done e.g. in LAMMPS)
 
std::vector< cvm::realatoms_charges
 Charges of the atoms (allow redefinition during a run, as done e.g. in LAMMPS)
 
std::vector< cvm::rvectoratoms_positions
 Current three-dimensional positions of the atoms.
 
std::vector< cvm::rvectoratoms_total_forces
 Most recent total forces on each atom.
 
std::vector< cvm::rvectoratoms_new_colvar_forces
 Forces applied from colvars, to be communicated to the MD integrator.
 
std::vector< int > atom_groups_ids
 Array of 0-based integers used to uniquely associate atom groups within the host program.
 
std::vector< size_t > atom_groups_ncopies
 Keep track of how many times each group is used by a separate cvc.
 
std::vector< cvm::realatom_groups_masses
 Total masses of the atom groups.
 
std::vector< cvm::realatom_groups_charges
 Total charges of the atom groups (allow redefinition during a run, as done e.g. in LAMMPS)
 
std::vector< cvm::rvectoratom_groups_coms
 Current centers of mass of the atom groups.
 
std::vector< cvm::rvectoratom_groups_total_forces
 Most recently updated total forces on the com of each group.
 
std::vector< cvm::rvectoratom_groups_new_colvar_forces
 Forces applied from colvars, to be communicated to the MD integrator.
 

Detailed Description

Interface between the collective variables module and the simulation or analysis program (NAMD, VMD, LAMMPS...). This is the base class: each interfaced program is supported by a derived class. Only pure virtual functions ("= 0") must be reimplemented to ensure baseline functionality.

Member Function Documentation

virtual int colvarproxy::init_atom ( cvm::residue_id const &  residue,
std::string const &  atom_name,
std::string const &  segment_id 
)
inlinevirtual

Select this atom for collective variables calculation, using name and residue number. Not all programs support this: leave this function as is in those cases.

Reimplemented in colvarproxy_namd, and colvarproxy_vmd.

virtual int colvarproxy::load_atoms ( char const *  filename,
cvm::atom_group atoms,
std::string const &  pdb_field,
double const  pdb_field_value = 0.0 
)
inlinevirtual

Read atom identifiers from a file.

Parameters
filenamename of the file (usually a PDB)
atomsarray to which atoms read from "filename" will be appended
pdb_field(optiona) if "filename" is a PDB file, use this field to determine which are the atoms to be set

Reimplemented in colvarproxy_namd, and colvarproxy_vmd.

virtual int colvarproxy::scalable_group_coms ( )
inlinevirtual

TODO Add here containers of handles to cvc objects that are computed in parallel.

Whether this proxy implementation has capability for scalable groups

Reimplemented in colvarproxy_namd.

virtual void colvarproxy::select_closest_image ( cvm::atom_pos pos,
cvm::atom_pos const &  ref_pos 
)
inlinevirtual

Get the closest periodic image to a reference position.

Parameters
posThe position to look for the closest periodic image
ref_posThe reference position

Reimplemented in colvarproxy_namd, and colvarproxy_vmd.

void colvarproxy::select_closest_images ( std::vector< cvm::atom_pos > &  pos,
cvm::atom_pos const &  ref_pos 
)
inline

Perform select_closest_image() on a set of atomic positions.

After that, distance vectors can then be calculated directly, without using position_distance()

virtual int colvarproxy::update_input ( )
inlinevirtual

Update data required by the colvars module (e.g. cache atom positions)

TODO Break up colvarproxy_namd and colvarproxy_lammps function into these

Reimplemented in colvarproxy_vmd.

Member Data Documentation

colvarscript* colvarproxy::script

Pointer to the scripting interface object (does not need to be allocated in a new interface)


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