Update Colvars to version 2022-05-09

This update includes one new feature (neural-network based collective
variables), several small enhancements (including an automatic definition of
grid boundaries for angle-based CVs, and a normalization option for
eigenvector-based CVs), bugfixes and documentation improvements.

Usage information for specific features included in the Colvars library
(i.e. not just the library as a whole) is now also reported to the screen or
LAMMPS logfile (as is done already in other LAMMPS classes).

Notable to LAMMPS code development are the removals of duplicated code and of
ambiguously-named preprocessor defines in the Colvars headers.  Since the
last PR, the existing regression tests have also been running automatically
via GitHub Actions.

The following pull requests in the Colvars repository are relevant to LAMMPS:

- 475 Remove fatal error condition
  https://github.com/Colvars/colvars/pull/475 (@jhenin, @giacomofiorin)

- 474 Allow normalizing eigenvector vector components to deal with unit change
  https://github.com/Colvars/colvars/pull/474 (@giacomofiorin, @jhenin)

- 470 Better error handling in the initialization of NeuralNetwork CV
  https://github.com/Colvars/colvars/pull/470 (@HanatoK)

- 468 Add examples of histogram configuration, with and without explicit grid parameters
  https://github.com/Colvars/colvars/pull/468 (@giacomofiorin)

- 464 Fix #463 using more fine-grained features
  https://github.com/Colvars/colvars/pull/464 (@jhenin, @giacomofiorin)

- 447 [RFC] New option "scaledBiasingForce" for colvarbias
  https://github.com/Colvars/colvars/pull/447 (@HanatoK, @jhenin)

- 444 [RFC] Implementation of dense neural network as CV
  https://github.com/Colvars/colvars/pull/444 (@HanatoK, @giacomofiorin, @jhenin)

- 443 Fix explicit gradient dependency of sub-CVs
  https://github.com/Colvars/colvars/pull/443 (@HanatoK, @jhenin)

- 442 Persistent bias count
  https://github.com/Colvars/colvars/pull/442 (@jhenin, @giacomofiorin)

- 437 Return type of bias from scripting interface
  https://github.com/Colvars/colvars/pull/437 (@giacomofiorin)

- 434 More flexible use of boundaries from colvars by grids
  https://github.com/Colvars/colvars/pull/434 (@jhenin)

- 433 Prevent double-free in linearCombination
  https://github.com/Colvars/colvars/pull/433 (@HanatoK)

- 428 More complete documentation for index file format (NDX)
  https://github.com/Colvars/colvars/pull/428 (@giacomofiorin)

- 426 Integrate functional version of backup_file() into base proxy class
  https://github.com/Colvars/colvars/pull/426 (@giacomofiorin)

- 424 Track CVC inheritance when documenting feature usage
  https://github.com/Colvars/colvars/pull/424 (@giacomofiorin)

- 419 Generate citation report while running computations
  https://github.com/Colvars/colvars/pull/419 (@giacomofiorin, @jhenin)

- 415 Rebin metadynamics bias from explicit hills when available
  https://github.com/Colvars/colvars/pull/415 (@giacomofiorin)

- 312 Ignore a keyword if it has content to the left of it (regardless of braces)
  https://github.com/Colvars/colvars/pull/312 (@giacomofiorin)

Authors: @giacomofiorin, @HanatoK, @jhenin
This commit is contained in:
Giacomo Fiorin
2022-05-10 11:24:54 -04:00
parent 4737b9efb7
commit 1220bea011
66 changed files with 4040 additions and 1221 deletions

View File

@ -9,6 +9,8 @@
#include <sstream>
#include <cstring>
#include <vector>
#include <map>
#include "colvarmodule.h"
#include "colvarparse.h"
@ -18,6 +20,7 @@
#include "colvarbias_abf.h"
#include "colvarbias_alb.h"
#include "colvarbias_histogram.h"
#include "colvarbias_histogram_reweight_amd.h"
#include "colvarbias_meta.h"
#include "colvarbias_restraint.h"
#include "colvarscript.h"
@ -25,6 +28,44 @@
#include "colvarcomp.h"
/// Track usage of Colvars features
class colvarmodule::usage {
public:
/// Constructor
usage();
/// Increment usage count for the given feature; return error if not found
int cite_feature(std::string const &feature);
/// Increment usage count for the given paper; return error if not found
int cite_paper(std::string const &paper);
/// Generate a report for used features (0 = URL, 1 = BibTeX)
std::string report(int flag);
protected:
/// Usage count for each feature
std::map<std::string, int> feature_count_;
/// Usage count for each cited paper
std::map<std::string, int> paper_count_;
/// URL for each paper
std::map<std::string, std::string> paper_url_;
/// BibTeX entry for each paper
std::map<std::string, std::string> paper_bibtex_;
/// Map code features to the relevant papers
std::map<std::string, std::string> feature_paper_map_;
};
colvarmodule::colvarmodule(colvarproxy *proxy_in)
{
depth_s = 0;
@ -34,27 +75,33 @@ colvarmodule::colvarmodule(colvarproxy *proxy_in)
xyz_reader_use_count = 0;
num_biases_types_used_ =
reinterpret_cast<void *>(new std::map<std::string, int>());
restart_version_str.clear();
restart_version_int = 0;
if (proxy == NULL) {
proxy = proxy_in; // Pointer to the proxy object
parse = new colvarparse(); // Parsing object for global options
version_int = proxy->get_version_from_string(COLVARS_VERSION);
} else {
usage_ = new usage();
usage_->cite_feature("Colvars module");
if (proxy != NULL) {
// TODO relax this error to handle multiple molecules in VMD
// once the module is not static anymore
cvm::error("Error: trying to allocate the collective "
"variable module twice.\n", BUG_ERROR);
"variable module twice.\n", COLVARS_BUG_ERROR);
return;
}
proxy = proxy_in; // Pointer to the proxy object
parse = new colvarparse(); // Parsing object for global options
version_int = proxy->get_version_from_string(COLVARS_VERSION);
cvm::log(cvm::line_marker);
cvm::log("Initializing the collective variables module, version "+
version()+".\n");
cvm::log("Please cite Fiorin et al, Mol Phys 2013:\n "
"https://dx.doi.org/10.1080/00268976.2013.813594\n"
"in any publication based on this calculation.\n");
cvm::log("Please cite Fiorin et al, Mol Phys 2013:\n"
" https://doi.org/10.1080/00268976.2013.813594\n"
"as well as all other papers listed below for individual features used.\n");
if (proxy->smp_enabled() == COLVARS_OK) {
cvm::log("SMP parallelism is enabled; if needed, use \"smp off\" to override this.\n");
@ -65,7 +112,7 @@ colvarmodule::colvarmodule(colvarproxy *proxy_in)
#else
cvm::log("This version was built without the C++11 standard: some features are disabled.\n"
"Please see the following link for details:\n"
"https://colvars.github.io/README-c++11.html");
" https://colvars.github.io/README-c++11.html\n");
#endif
// set initial default values
@ -87,8 +134,10 @@ colvarmodule::colvarmodule(colvarproxy *proxy_in)
// by default overwrite the existing trajectory file
cv_traj_append = false;
cv_traj_write_labels = true;
// Removes the need for proxy specializations to create this
proxy->script = new colvarscript(proxy, this);
}
@ -145,7 +194,7 @@ int colvarmodule::read_config_file(char const *config_filename)
if (!config_s.is_open()) {
cvm::error("Error: in opening configuration file \""+
std::string(config_filename)+"\".\n",
FILE_ERROR);
COLVARS_FILE_ERROR);
return COLVARS_ERROR;
}
@ -210,7 +259,7 @@ int colvarmodule::parse_config(std::string &conf)
// Check that the input has matching braces
if (colvarparse::check_braces(conf, 0) != COLVARS_OK) {
return cvm::error("Error: unmatched curly braces in configuration.\n",
INPUT_ERROR);
COLVARS_INPUT_ERROR);
}
// Check that the input has only ASCII characters, and warn otherwise
@ -253,6 +302,10 @@ int colvarmodule::parse_config(std::string &conf)
// Update any necessary proxy data
proxy->setup();
if (source_Tcl_script.size() > 0) {
run_tcl_script(source_Tcl_script);
}
return get_error();
}
@ -342,20 +395,26 @@ int colvarmodule::parse_global_params(std::string const &conf)
parse->get_keyval(conf, "scriptingAfterBiases",
scripting_after_biases, scripting_after_biases);
if (use_scripted_forces && !proxy->force_script_defined) {
if (proxy->simulation_running()) {
return cvm::error("User script for scripted colvar forces not found.",
INPUT_ERROR);
} else {
// Not necessary if we are not applying biases in a real simulation (eg. VMD)
cvm::log("Warning: User script for scripted colvar forces not found.");
}
}
#if defined(COLVARS_TCL)
parse->get_keyval(conf, "sourceTclFile", source_Tcl_script);
#endif
return cvm::get_error();
}
int colvarmodule::run_tcl_script(std::string const &filename) {
int result = COLVARS_OK;
#if defined(COLVARS_TCL)
result = proxy->tcl_run_file(filename);
#endif
return result;
}
int colvarmodule::parse_colvars(std::string const &conf)
{
if (cvm::debug())
@ -378,7 +437,7 @@ int colvarmodule::parse_colvars(std::string const &conf)
}
cvm::decrease_depth();
} else {
cvm::error("Error: \"colvar\" keyword found without any configuration.\n", INPUT_ERROR);
cvm::error("Error: \"colvar\" keyword found without any configuration.\n", COLVARS_INPUT_ERROR);
return COLVARS_ERROR;
}
cvm::decrease_depth();
@ -421,13 +480,27 @@ template <class bias_type>
int colvarmodule::parse_biases_type(std::string const &conf,
char const *keyword)
{
// Allow camel case when calling, but use only lower case for parsing
std::string const &type_keyword = colvarparse::to_lower_cppstr(keyword);
// Check how many times this bias keyword was used, set default name
// accordingly
std::map<std::string, int> *num_biases_types_used =
reinterpret_cast<std::map<std::string, int> *>(num_biases_types_used_);
if (num_biases_types_used->count(type_keyword) == 0) {
(*num_biases_types_used)[type_keyword] = 0;
}
std::string bias_conf = "";
size_t conf_saved_pos = 0;
while (parse->key_lookup(conf, keyword, &bias_conf, &conf_saved_pos)) {
if (bias_conf.size()) {
cvm::log(cvm::line_marker);
cvm::increase_depth();
biases.push_back(new bias_type(keyword));
int &bias_count = (*num_biases_types_used)[type_keyword];
biases.push_back(new bias_type(type_keyword.c_str()));
bias_count += 1;
biases.back()->rank = bias_count;
biases.back()->init(bias_conf);
if (cvm::check_new_bias(bias_conf, keyword) != COLVARS_OK) {
return COLVARS_ERROR;
@ -435,7 +508,7 @@ int colvarmodule::parse_biases_type(std::string const &conf,
cvm::decrease_depth();
} else {
cvm::error("Error: keyword \""+std::string(keyword)+"\" found without configuration.\n",
INPUT_ERROR);
COLVARS_INPUT_ERROR);
return COLVARS_ERROR;
}
bias_conf = "";
@ -477,6 +550,9 @@ int colvarmodule::parse_biases(std::string const &conf)
/// initialize metadynamics instances
parse_biases_type<colvarbias_meta>(conf, "metadynamics");
/// initialize reweightaMD instances
parse_biases_type<colvarbias_reweightaMD>(conf, "reweightaMD");
if (use_scripted_forces) {
cvm::log(cvm::line_marker);
cvm::increase_depth();
@ -580,8 +656,8 @@ int colvarmodule::catch_input_errors(int result)
{
if (result != COLVARS_OK || get_error()) {
set_error_bits(result);
set_error_bits(INPUT_ERROR);
parse->init();
set_error_bits(COLVARS_INPUT_ERROR);
parse->clear();
return get_error();
}
return COLVARS_OK;
@ -1017,7 +1093,7 @@ int colvarmodule::write_restart_file(std::string const &out_name)
std::ostream *restart_out_os = proxy->output_stream(out_name);
if (!restart_out_os) return cvm::get_error();
if (!write_restart(*restart_out_os)) {
return cvm::error("Error: in writing restart file.\n", FILE_ERROR);
return cvm::error("Error: in writing restart file.\n", COLVARS_FILE_ERROR);
}
proxy->close_output_stream(out_name);
if (cv_traj_os != NULL) {
@ -1033,7 +1109,7 @@ int colvarmodule::write_restart_string(std::string &output)
cvm::log("Saving state to output buffer.\n");
std::ostringstream os;
if (!write_restart(os)) {
return cvm::error("Error: in writing restart to buffer.\n", FILE_ERROR);
return cvm::error("Error: in writing restart to buffer.\n", COLVARS_FILE_ERROR);
}
output = os.str();
return COLVARS_OK;
@ -1156,8 +1232,17 @@ colvarmodule::~colvarmodule()
colvar::cvc::delete_features();
atom_group::delete_features();
delete
reinterpret_cast<std::map<std::string, int> *>(num_biases_types_used_);
num_biases_types_used_ = NULL;
delete parse;
parse = NULL;
delete usage_;
usage_ = NULL;
// The proxy object will be deallocated last (if at all)
proxy = NULL;
}
}
@ -1167,7 +1252,7 @@ int colvarmodule::reset()
{
cvm::log("Resetting the Collective Variables module.\n");
parse->init();
parse->clear();
// Iterate backwards because we are deleting the elements as we go
for (std::vector<colvarbias *>::reverse_iterator bi = biases.rbegin();
@ -1178,6 +1263,9 @@ int colvarmodule::reset()
biases.clear();
biases_active_.clear();
// Reset counters tracking usage of each bias type
reinterpret_cast<std::map<std::string, int> *>(num_biases_types_used_)->clear();
// Iterate backwards because we are deleting the elements as we go
for (std::vector<colvar *>::reverse_iterator cvi = colvars.rbegin();
cvi != colvars.rend();
@ -1215,7 +1303,7 @@ int colvarmodule::setup_input()
if (!input_is.good()) {
return cvm::error("Error: in opening input state file \""+
std::string(restart_in_name)+"\".\n",
FILE_ERROR);
COLVARS_FILE_ERROR);
} else {
cvm::log(cvm::line_marker);
cvm::log("Loading state from file \""+restart_in_name+"\".\n");
@ -1287,7 +1375,7 @@ int colvarmodule::setup_output()
}
if (error_code != COLVARS_OK || cvm::get_error()) {
set_error_bits(FILE_ERROR);
set_error_bits(COLVARS_FILE_ERROR);
}
return cvm::get_error();
@ -1301,7 +1389,7 @@ std::string colvarmodule::state_file_prefix(char const *filename)
filename_str.substr(0, filename_str.find(".colvars.state"));
if (prefix.size() == 0) {
cvm::error("Error: invalid filename/prefix value \""+filename_str+"\".",
INPUT_ERROR);
COLVARS_INPUT_ERROR);
}
return prefix;
}
@ -1353,7 +1441,7 @@ std::istream & colvarmodule::read_restart(std::istream &is)
if ((proxy->units.size() > 0) && (units_restart != proxy->units)) {
cvm::error("Error: the state file has units \""+units_restart+
"\", but the current unit system is \""+proxy->units+
"\".\n", INPUT_ERROR);
"\".\n", COLVARS_INPUT_ERROR);
}
}
@ -1396,7 +1484,7 @@ std::istream & colvarmodule::read_objects_state(std::istream &is)
// state is corrupt; otherwise, the variable rewinds is silently
cvm::error("Error: in reading restart configuration for "
"collective variable \""+(*cvi)->name+"\".\n",
INPUT_ERROR);
COLVARS_INPUT_ERROR);
}
if (is.tellg() > pos) break; // found it
}
@ -1417,7 +1505,7 @@ std::istream & colvarmodule::read_objects_state(std::istream &is)
// Same as above, an error means a match but the state is incorrect
cvm::error("Error: in reading restart configuration for bias \""+
(*bi)->name+"\".\n",
INPUT_ERROR);
COLVARS_INPUT_ERROR);
}
if (is.tellg() > pos) break; // found it
}
@ -1455,7 +1543,7 @@ and load it to continue this simulation.\n");
output_prefix() = output_prefix()+".tmp";
write_restart_file(output_prefix()+".colvars.state");
return cvm::error("Exiting with error until issue is addressed.\n",
INPUT_ERROR);
COLVARS_INPUT_ERROR);
}
return COLVARS_OK;
@ -1533,7 +1621,7 @@ int colvarmodule::read_traj(char const *traj_filename,
std::cerr << "\n";
cvm::error("Reached the end of the trajectory, "
"read_end = "+cvm::to_str(traj_read_end)+"\n",
FILE_ERROR);
COLVARS_FILE_ERROR);
return COLVARS_ERROR;
}
@ -1544,7 +1632,7 @@ int colvarmodule::read_traj(char const *traj_filename,
cvm::error("Error: in reading colvar \""+(*cvi)->name+
"\" from trajectory file \""+
std::string(traj_filename)+"\".\n",
FILE_ERROR);
COLVARS_FILE_ERROR);
return COLVARS_ERROR;
}
}
@ -1613,7 +1701,7 @@ int colvarmodule::open_traj_file(std::string const &file_name)
if (cv_traj_os == NULL) {
cvm::error("Error: cannot write to file \""+file_name+"\".\n",
FILE_ERROR);
COLVARS_FILE_ERROR);
}
return cvm::get_error();
@ -1739,7 +1827,7 @@ size_t & colvarmodule::depth()
void colvarmodule::set_error_bits(int code)
{
if (code < 0) {
cvm::fatal_error("Error: set_error_bits() received negative error code.\n");
cvm::log("Error: set_error_bits() received negative error code.\n");
return;
}
proxy->smp_lock();
@ -1771,19 +1859,13 @@ int colvarmodule::error(std::string const &message, int code)
}
int colvarmodule::fatal_error(std::string const &message)
{
return error(message, FATAL_ERROR);
}
int cvm::read_index_file(char const *filename)
{
std::ifstream is(filename, std::ios::binary);
if (!is.good()) {
cvm::error("Error: in opening index file \""+
return cvm::error("Error: in opening index file \""+
std::string(filename)+"\".\n",
FILE_ERROR);
COLVARS_FILE_ERROR);
} else {
index_file_names.push_back(std::string(filename));
}
@ -1810,7 +1892,7 @@ int cvm::read_index_file(char const *filename)
} else {
return cvm::error("Error: in parsing index file \""+
std::string(filename)+"\".\n",
INPUT_ERROR);
COLVARS_INPUT_ERROR);
}
std::vector<int> *old_index_group = index_groups[index_of_group];
@ -1836,7 +1918,7 @@ int cvm::read_index_file(char const *filename)
delete new_index_group;
new_index_group = NULL;
return cvm::error("Error: the index group \""+group_name+
"\" was redefined.\n", INPUT_ERROR);
"\" was redefined.\n", COLVARS_INPUT_ERROR);
} else {
old_index_group->clear();
delete old_index_group;
@ -1912,7 +1994,7 @@ int cvm::load_coords(char const *file_name,
if (colvarparse::to_lower_cppstr(ext) == std::string(".xyz")) {
if (pdb_field.size() > 0) {
return cvm::error("Error: PDB column may not be specified "
"for XYZ coordinate files.\n", INPUT_ERROR);
"for XYZ coordinate files.\n", COLVARS_INPUT_ERROR);
}
// For XYZ files, use internal parser
error_code |= cvm::main()->load_coords_xyz(file_name, &sorted_pos, atoms);
@ -1946,7 +2028,7 @@ int cvm::load_coords_xyz(char const *filename,
std::string(filename)+"\".\n");
if ( ! (xyz_is >> natoms) ) {
return cvm::error(error_msg, INPUT_ERROR);
return cvm::error(error_msg, COLVARS_INPUT_ERROR);
}
++xyz_reader_use_count;
@ -1960,7 +2042,7 @@ int cvm::load_coords_xyz(char const *filename,
cvm::getline(xyz_is, line);
xyz_is.width(255);
} else {
return cvm::error(error_msg, INPUT_ERROR);
return cvm::error(error_msg, COLVARS_INPUT_ERROR);
}
std::vector<atom_pos>::iterator pos_i = pos->begin();
@ -1983,7 +2065,7 @@ int cvm::load_coords_xyz(char const *filename,
(*pos_i)[2] = proxy->angstrom_to_internal(z);
xyz_natoms++;
} else {
return cvm::error(error_msg, INPUT_ERROR);
return cvm::error(error_msg, COLVARS_INPUT_ERROR);
}
}
@ -1998,7 +2080,7 @@ int cvm::load_coords_xyz(char const *filename,
(*pos_i)[2] = proxy->angstrom_to_internal(z);
xyz_natoms++;
} else {
return cvm::error(error_msg, INPUT_ERROR);
return cvm::error(error_msg, COLVARS_INPUT_ERROR);
}
}
}
@ -2007,7 +2089,7 @@ int cvm::load_coords_xyz(char const *filename,
return cvm::error("Error: The number of positions read from file \""+
std::string(filename)+"\" does not match the number of "+
"positions required: "+cvm::to_str(xyz_natoms)+" vs. "+
cvm::to_str(pos->size())+".\n", INPUT_ERROR);
cvm::to_str(pos->size())+".\n", COLVARS_INPUT_ERROR);
}
return COLVARS_OK;
@ -2230,6 +2312,89 @@ std::string cvm::wrap_string(std::string const &s, size_t nchars)
}
int colvarmodule::cite_feature(std::string const &feature)
{
return usage_->cite_feature(feature);
}
std::string colvarmodule::feature_report(int flag)
{
return usage_->report(flag);
}
colvarmodule::usage::usage()
{
#include "colvarmodule_refs.h"
}
int colvarmodule::usage::cite_feature(std::string const &feature)
{
if (feature_count_.count(feature) > 0) {
feature_count_[feature] += 1;
return cite_paper(feature_paper_map_[feature]);
}
cvm::log("Warning: cannot cite unknown feature \""+feature+"\"\n");
return COLVARS_OK;
}
int colvarmodule::usage::cite_paper(std::string const &paper)
{
if (paper_count_.count(paper) > 0) {
paper_count_[paper] += 1;
return COLVARS_OK;
}
cvm::log("Warning: cannot cite unknown paper \""+paper+"\"\n");
return COLVARS_OK;
}
std::string colvarmodule::usage::report(int flag)
{
std::string result;
if (flag == 0) {
// Text
result += "SUMMARY OF COLVARS FEATURES USED SO FAR AND THEIR CITATIONS:\n";
}
if (flag == 1) {
// LAMMPS log friendly (one-line summary, lowercase message)
result += "Colvars module (Fiorin2013, plus other works listed for specific features)\n\n";
}
std::map<std::string, int>::iterator p_iter = paper_count_.begin();
for ( ; p_iter != paper_count_.end(); p_iter++) {
std::string const paper = p_iter->first;
int const count = p_iter->second;
if (count > 0) {
result += "\n";
std::map<std::string, std::string>::iterator f_iter =
feature_paper_map_.begin();
for ( ; f_iter != feature_paper_map_.end(); f_iter++) {
if ((f_iter->second == paper) &&
(feature_count_[f_iter->first] > 0)) {
if (flag == 0) {
// URL
result += "- " + f_iter->first + ":\n";
}
if (flag == 1) {
// BibTeX
result += "% " + f_iter->first + ":\n";
}
}
}
if (flag == 0) {
result += " " + paper + " " + paper_url_[paper] + "\n";
}
if (flag == 1) {
result += paper_bibtex_[paper] + "\n";
}
}
}
return result;
}
// shared pointer to the proxy object
colvarproxy *colvarmodule::proxy = NULL;