colvarscript_commands.h

00001 // -*- c++ -*-
00002 
00003 // This file is part of the Collective Variables module (Colvars).
00004 // The original version of Colvars and its updates are located at:
00005 // https://github.com/Colvars/colvars
00006 // Please update all Colvars source files before making any changes.
00007 // If you wish to distribute your changes, please submit them to the
00008 // Colvars repository at GitHub.
00009 
00010 #ifndef COLVARSCRIPT_COMMANDS_H
00011 #define COLVARSCRIPT_COMMANDS_H
00012 
00013 // The following is a complete definition of the scripting API.
00014 
00015 // The CVSCRIPT macro is used in four distinct contexts:
00016 // 1) Expand to the functions' prototypes (when included generically)
00017 // 2) List colvarscript::command entries (when included in colvarscript.h)
00018 // 3) Implement colvarscript::init() (when included in colvarscript.cpp)
00019 // 4) Define the functions' bodies (when included in colvarscript_commands.cpp)
00020 
00021 
00022 // Each command is created by an instance of the CVSCRIPT macro
00023 
00024 // The arguments of the CVSCRIPT macro are:
00025 
00026 // COMM = the id of the command (must be a member of colvarscript::command)
00027 
00028 // HELP = short description (C string literal) for the command; the second line
00029 // is optional, and documents the return value (if any)
00030 
00031 // N_ARGS_MIN = the lowest number of arguments allowed
00032 
00033 // N_ARGS_MAX = the highest number of arguments allowed
00034 
00035 // ARGS = multi-line string literal describing each parameter; each line
00036 // follows the format "name : type - description"
00037 
00038 // FN_BODY = the implementation of the function; this should be a thin wrapper
00039 // over existing functions; the "script" pointer to the colvarscript
00040 // object is already set by the CVSCRIPT_COMM_FN macro; see also the
00041 // functions in colvarscript_commands.h.
00042 
00043 #ifndef CVSCRIPT_COMM_FNAME
00044 #define CVSCRIPT_COMM_FNAME(COMM) cvscript_ ## COMM
00045 #endif
00046 
00047 // If CVSCRIPT is not defined, this file yields the function prototypes
00048 #ifndef CVSCRIPT
00049 
00050 #ifdef __cplusplus
00051 #define CVSCRIPT_COMM_PROTO(COMM) \
00052 extern "C" int CVSCRIPT_COMM_FNAME(COMM)(void *, \
00053 int, unsigned char *const *);
00054 #else
00055 #define CVSCRIPT_COMM_PROTO(COMM) \
00056 int CVSCRIPT_COMM_FNAME(COMM)(void *, int, unsigned char *const *);
00057 #endif
00058 
00059 #define CVSCRIPT(COMM,HELP,N_ARGS_MIN,N_ARGS_MAX,ARGS,FN_BODY) \
00060 CVSCRIPT_COMM_PROTO(COMM)
00061 
00062 
00063 // Utility functions used to query the command database
00064 extern "C" {
00065 
00067 int cvscript_n_commands();
00068 
00070 char const ** cvscript_command_names();
00071 
00074 char const *cvscript_command_help(char const *cmd);
00075 
00078 char const *cvscript_command_rethelp(char const *cmd);
00079 
00085 char const *cvscript_command_arghelp(char const *cmd, int i);
00086 
00089 char const *cvscript_command_full_help(char const *cmd);
00090 
00093 int cvscript_command_n_args_min(char const *cmd);
00094 
00097 int cvscript_command_n_args_max(char const *cmd);
00098 
00099 }
00100 
00101 #endif
00102 
00103 
00104 CVSCRIPT(cv_addenergy,
00105 "Add an energy to the MD engine (no effect in VMD)",
00106 1, 1,
00107 "E : float - Amount of energy to add",
00108 char const *Earg =
00109 script->obj_to_str(script->get_module_cmd_arg(0, objc, objv));
00110 cvm::main()->total_bias_energy += strtod(Earg, NULL);
00111 return cvm::get_error(); // TODO Make this multi-language
00112 )
00113 
00114 CVSCRIPT(cv_bias,
00115 "Prefix for bias-specific commands",
00116 0, 0,
00117 "",
00118 // This cannot be executed from a command line
00119 return COLVARS_OK;
00120 )
00121 
00122 CVSCRIPT(cv_colvar,
00123 "Prefix for colvar-specific commands",
00124 0, 0,
00125 "",
00126 // This cannot be executed from a command line
00127 return COLVARS_OK;
00128 )
00129 
00130 CVSCRIPT(cv_config,
00131 "Read configuration from the given string",
00132 1, 1,
00133 "conf : string - Configuration string",
00134 char const *conf_str =
00135 script->obj_to_str(script->get_module_cmd_arg(0, objc, objv));
00136 std::string const conf(conf_str);
00137 script->proxy()->add_config("config", conf);
00138 if (script->proxy()->engine_ready()) {
00139 // Engine allows immediate initialization
00140 if ((script->proxy()->parse_module_config() |
00141 script->proxy()->setup()) == COLVARS_OK) {
00142 return COLVARS_OK;
00143 } else {
00144 script->add_error_msg("Error parsing configuration string");
00145 return COLVARSCRIPT_ERROR;
00146 }
00147 }
00148 // Engine not ready, config will be read during proxy->setup()
00149 return COLVARS_OK;
00150 )
00151 
00152 CVSCRIPT(cv_configfile,
00153 "Read configuration from a file",
00154 1, 1,
00155 "conf_file : string - Path to configuration file",
00156 char const *conf_file_name =
00157 script->obj_to_str(script->get_module_cmd_arg(0, objc, objv));
00158 script->proxy()->add_config("configfile", std::string(conf_file_name));
00159 if (script->proxy()->engine_ready()) {
00160 // Engine allows immediate initialization
00161 if ((script->proxy()->parse_module_config() |
00162 script->proxy()->setup()) == COLVARS_OK) {
00163 return COLVARS_OK;
00164 } else {
00165 script->add_error_msg("Error parsing configuration file");
00166 return COLVARSCRIPT_ERROR;
00167 }
00168 }
00169 // Engine not ready, config will be read during proxy->setup()
00170 return COLVARS_OK;
00171 )
00172 
00173 CVSCRIPT(cv_delete,
00174 "Delete this Colvars module instance (VMD only)",
00175 0, 0,
00176 "",
00177 return script->proxy()->request_deletion();
00178 )
00179 
00180 CVSCRIPT(cv_featurereport,
00181 "Return a summary of Colvars features used so far and their citations\n"
00182 "report : string - Feature report and citations",
00183 0, 0,
00184 "",
00185 return script->set_result_str(script->module()->feature_report());
00186 )
00187 
00188 CVSCRIPT(cv_frame,
00189 "Get or set current frame number (VMD only)\n"
00190 "frame : integer - Frame number",
00191 0, 1,
00192 "frame : integer - Frame number",
00193 char const *arg =
00194 script->obj_to_str(script->get_module_cmd_arg(0, objc, objv));
00195 if (arg == NULL) {
00196 long int f = -1;
00197 if (script->proxy()->get_frame(f) == COLVARS_OK) {
00198 script->set_result_long_int(f);
00199 return COLVARS_OK;
00200 } else {
00201 script->add_error_msg("Frame number is not available");
00202 return COLVARSCRIPT_ERROR;
00203 }
00204 } else {
00205 int const f = strtol(const_cast<char *>(arg), NULL, 10);
00206 int error_code = script->proxy()->set_frame(f);
00207 if (error_code == COLVARS_NO_SUCH_FRAME) {
00208 script->add_error_msg("Invalid frame number: \""+std::string(arg)+
00209 "\"\n");
00210 }
00211 return error_code;
00212 }
00213 return COLVARS_OK;
00214 )
00215 
00216 CVSCRIPT(cv_getatomappliedforces,
00217 "Get the list of forces applied by Colvars to atoms\n"
00218 "forces : array of arrays of floats - Atomic forces",
00219 0, 0,
00220 "",
00221 script->set_result_rvector_vec(*(script->proxy()->get_atom_applied_forces()));
00222 return COLVARS_OK;
00223 )
00224 
00225 CVSCRIPT(cv_getatomappliedforcesmax,
00226 "Get the maximum norm of forces applied by Colvars to atoms\n"
00227 "force : float - Maximum atomic force",
00228 0, 0,
00229 "",
00230 script->set_result_real(script->proxy()->max_atoms_applied_force());
00231 return COLVARS_OK;
00232 )
00233 
00234 CVSCRIPT(cv_getatomappliedforcesmaxid,
00235 "Get the atom ID with the largest applied force\n"
00236 "id : int - ID of the atom with the maximum atomic force",
00237 0, 0,
00238 "",
00239 script->set_result_int(script->proxy()->max_atoms_applied_force_id());
00240 return COLVARS_OK;
00241 )
00242 
00243 CVSCRIPT(cv_getatomappliedforcesrms,
00244 "Get the root-mean-square norm of forces applied by Colvars to atoms\n"
00245 "force : float - RMS atomic force",
00246 0, 0,
00247 "",
00248 script->set_result_real(script->proxy()->rms_atoms_applied_force());
00249 return COLVARS_OK;
00250 )
00251 
00252 CVSCRIPT(cv_resetatomappliedforces,
00253 "Reset forces applied by Colvars to atoms",
00254 0, 0,
00255 "",
00256 size_t i;
00257 std::vector<cvm::rvector> *f = script->proxy()->modify_atom_applied_forces();
00258 for (i = 0; i < f->size(); i++) {
00259 (*f)[i].reset();
00260 }
00261 return COLVARS_OK;
00262 )
00263 
00264 CVSCRIPT(cv_getatomids,
00265 "Get the list of indices of atoms used in Colvars\n"
00266 "indices : array of ints - Atom indices",
00267 0, 0,
00268 "",
00269 script->set_result_int_vec(*(script->proxy()->get_atom_ids()));
00270 return COLVARS_OK;
00271 )
00272 
00273 CVSCRIPT(cv_getatomcharges,
00274 "Get the list of charges of atoms used in Colvars\n"
00275 "charges : array of floats - Atomic charges",
00276 0, 0,
00277 "",
00278 script->set_result_real_vec(*(script->proxy()->get_atom_charges()));
00279 return COLVARS_OK;
00280 )
00281 
00282 CVSCRIPT(cv_getatommasses,
00283 "Get the list of masses of atoms used in Colvars\n"
00284 "masses : array of floats - Atomic masses",
00285 0, 0,
00286 "",
00287 script->set_result_real_vec(*(script->proxy()->get_atom_masses()));
00288 return COLVARS_OK;
00289 )
00290 
00291 CVSCRIPT(cv_getatompositions,
00292 "Get the list of cached positions of atoms used in Colvars\n"
00293 "positions : array of arrays of floats - Atomic positions",
00294 0, 0,
00295 "",
00296 script->set_result_rvector_vec(*(script->proxy()->get_atom_positions()));
00297 return COLVARS_OK;
00298 )
00299 
00300 CVSCRIPT(cv_getatomtotalforces,
00301 "Get the list of cached total forces of atoms used in Colvars\n"
00302 "forces : array of arrays of floats - Atomic total foces",
00303 0, 0,
00304 "",
00305 script->set_result_rvector_vec(*(script->proxy()->get_atom_total_forces()));
00306 return COLVARS_OK;
00307 )
00308 
00309 CVSCRIPT(cv_getconfig,
00310 "Get the module's configuration string read so far\n"
00311 "conf : string - Current configuration string",
00312 0, 0,
00313 "",
00314 script->set_result_str(cvm::main()->get_config());
00315 return COLVARS_OK;
00316 )
00317 
00318 CVSCRIPT(cv_getenergy,
00319 "Get the current Colvars energy\n"
00320 "E : float - Amount of energy (internal units)",
00321 0, 0,
00322 "",
00323 script->set_result_real(cvm::main()->total_bias_energy);
00324 return COLVARS_OK;
00325 )
00326 
00327 CVSCRIPT(cv_getnumactiveatomgroups,
00328 "Get the number of atom groups that currently have positive ref counts\n"
00329 "count : integer - Total number of atom groups",
00330 0, 0,
00331 "",
00332 script->set_result_int(static_cast<int>(script->proxy()->get_num_active_atom_groups()));
00333 return COLVARS_OK;
00334 )
00335 
00336 CVSCRIPT(cv_getnumactiveatoms,
00337 "Get the number of atoms that currently have positive ref counts\n"
00338 "count : integer - Total number of atoms",
00339 0, 0,
00340 "",
00341 script->set_result_int(static_cast<int>(script->proxy()->get_num_active_atoms()));
00342 return COLVARS_OK;
00343 )
00344 
00345 CVSCRIPT(cv_getnumatoms,
00346 "Get the number of requested atoms, including those not in use now\n"
00347 "count : integer - Total number of atoms",
00348 0, 0,
00349 "",
00350 script->set_result_int(static_cast<int>(script->proxy()->get_atom_ids()->size()));
00351 return COLVARS_OK;
00352 )
00353 
00354 CVSCRIPT(cv_getstepabsolute,
00355 "Get the current step number of the simulation (including restarts)\n"
00356 "step : int - Absolute step number",
00357 0, 0,
00358 "",
00359 script->set_result_int(cvm::step_absolute());
00360 return COLVARS_OK;
00361 )
00362 
00363 CVSCRIPT(cv_getsteprelative,
00364 "Get the current step number from the start of this job\n"
00365 "step : int - Relative step number",
00366 0, 0,
00367 "",
00368 script->set_result_int(cvm::step_relative());
00369 return COLVARS_OK;
00370 )
00371 
00372 CVSCRIPT(cv_help,
00373 "Get the help string of the Colvars scripting interface\n"
00374 "help : string - Help string",
00375 0, 1,
00376 "command : string - Get the help string of this specific command",
00377 unsigned char *const cmdobj =
00378 script->get_module_cmd_arg(0, objc, objv);
00379 if (cmdobj) {
00380 std::string const cmdstr(script->obj_to_str(cmdobj));
00381 if (cmdstr.size()) {
00382 if (cmdstr == std::string("colvar")) {
00383 script->set_result_str(script->get_cmdline_help_summary(colvarscript::use_colvar));
00384 } else if (cmdstr == std::string("bias")) {
00385 script->set_result_str(script->get_cmdline_help_summary(colvarscript::use_bias));
00386 } else {
00387 script->set_result_str(script->get_command_cmdline_help(colvarscript::use_module,
00388 cmdstr));
00389 }
00390 return cvm::get_error();
00391 } else {
00392 return COLVARSCRIPT_ERROR;
00393 }
00394 } else {
00395 script->set_result_str(script->get_cmdline_help_summary(colvarscript::use_module));
00396 return COLVARS_OK;
00397 }
00398 )
00399 
00400 CVSCRIPT(cv_languageversion,
00401 "Get the C++ language version number\n"
00402 "version : string - C++ language version",
00403 0, 0,
00404 "",
00405 script->set_result_int(__cplusplus);
00406 return COLVARS_OK;
00407 )
00408 
00409 CVSCRIPT(cv_list,
00410 "Return a list of all variables or biases\n"
00411 "list : sequence of strings - List of elements",
00412 0, 1,
00413 "param : string - \"colvars\" or \"biases\"; default is \"colvars\"",
00414 std::string res;
00415 unsigned char *const kwarg = script->get_module_cmd_arg(0, objc, objv);
00416 std::string const kwstr = kwarg ? script->obj_to_str(kwarg) :
00417 std::string("colvars");
00418 if (kwstr == "colvars") {
00419 for (std::vector<colvar *>::iterator cvi = script->module()->variables()->begin();
00420 cvi != script->module()->variables()->end();
00421 ++cvi) {
00422 res += (cvi == script->module()->variables()->begin() ? "" : " ") + (*cvi)->name;
00423 }
00424 script->set_result_str(res);
00425 return COLVARS_OK;
00426 } else if (kwstr == "biases") {
00427 for (std::vector<colvarbias *>::iterator bi = script->module()->biases.begin();
00428 bi != script->module()->biases.end();
00429 ++bi) {
00430 res += (bi == script->module()->biases.begin() ? "" : " ") + (*bi)->name;
00431 }
00432 script->set_result_str(res);
00433 return COLVARS_OK;
00434 } else {
00435 script->add_error_msg("Wrong arguments to command \"list\"\n");
00436 return COLVARSCRIPT_ERROR;
00437 }
00438 )
00439 
00440 CVSCRIPT(cv_listcommands,
00441 "Get the list of script functions, prefixed with \"cv_\", \"colvar_\" or \"bias_\"\n"
00442 "list : sequence of strings - List of commands",
00443 0, 0,
00444 "",
00445 int const n_commands = cvscript_n_commands();
00446 char const **command_names = cvscript_command_names();
00447 std::string result;
00448 for (int i = 0; i < n_commands; i++) {
00449 if (i > 0) result.append(1, ' ');
00450 result.append(std::string(command_names[i]));
00451 }
00452 script->set_result_str(result);
00453 return COLVARS_OK;
00454 )
00455 
00456 CVSCRIPT(cv_listindexfiles,
00457 "Get a list of the index files loaded in this session",
00458 0, 0,
00459 "",
00460 int const n_files = script->module()->index_file_names.size();
00461 std::string result;
00462 for (int i = 0; i < n_files; i++) {
00463 if (i > 0) result.append(1, ' ');
00464 result.append(script->module()->index_file_names[i]);
00465 }
00466 script->set_result_str(result);
00467 return COLVARS_OK;
00468 )
00469 
00470 CVSCRIPT(cv_load,
00471 "Load data from a state file into all matching colvars and biases",
00472 1, 1,
00473 "prefix : string - Path to existing state file or input prefix",
00474 char const *arg =
00475 script->obj_to_str(script->get_module_cmd_arg(0, objc, objv));
00476 script->proxy()->input_prefix() = cvm::state_file_prefix(arg);
00477 if (script->module()->setup_input() == COLVARS_OK) {
00478 return COLVARS_OK;
00479 } else {
00480 script->add_error_msg("Error loading state file");
00481 return COLVARSCRIPT_ERROR;
00482 }
00483 )
00484 
00485 CVSCRIPT(cv_loadfromstring,
00486 "Load state data from a string into all matching colvars and biases",
00487 1, 1,
00488 "buffer : string - String buffer containing the state information",
00489 char const *arg =
00490 script->obj_to_str(script->get_module_cmd_arg(0, objc, objv));
00491 script->proxy()->input_buffer() = arg;
00492 if (script->module()->setup_input() == COLVARS_OK) {
00493 return COLVARS_OK;
00494 } else {
00495 script->add_error_msg("Error loading state string");
00496 return COLVARSCRIPT_ERROR;
00497 }
00498 )
00499 
00500 CVSCRIPT(cv_molid,
00501 "Get or set the molecule ID on which Colvars is defined (VMD only)\n"
00502 "molid : integer - Current molecule ID",
00503 0, 1,
00504 "molid : integer - New molecule ID; -1 means undefined",
00505 char const *arg =
00506 script->obj_to_str(script->get_module_cmd_arg(0, objc, objv));
00507 if (arg == NULL) {
00508 int molid = -1;
00509 script->proxy()->get_molid(molid);
00510 script->set_result_int(molid);
00511 return COLVARS_OK;
00512 } else {
00513 script->add_error_msg("Error: To change the molecule ID in VMD, use cv delete first.");
00514 return COLVARS_NOT_IMPLEMENTED;
00515 }
00516 )
00517 
00518 CVSCRIPT(cv_printframe,
00519 "Return the values that would be written to colvars.traj\n"
00520 "values : string - The values\n",
00521 0, 0,
00522 "",
00523 std::ostringstream os;
00524 script->module()->write_traj(os);
00525 script->set_result_str(os.str());
00526 return COLVARS_OK;
00527 )
00528 
00529 CVSCRIPT(cv_printframelabels,
00530 "Return the labels that would be written to colvars.traj\n"
00531 "Labels : string - The labels",
00532 0, 0,
00533 "",
00534 std::ostringstream os;
00535 script->module()->write_traj_label(os);
00536 script->set_result_str(os.str());
00537 return COLVARS_OK;
00538 )
00539 
00540 CVSCRIPT(cv_reset,
00541 "Delete all internal configuration",
00542 0, 0,
00543 "",
00544 return script->module()->reset();
00545 )
00546 
00547 CVSCRIPT(cv_resetindexgroups,
00548 "Clear the index groups loaded so far, allowing to replace them",
00549 0, 0,
00550 "",
00551 cvm::main()->index_group_names.clear();
00552 cvm::main()->index_groups.clear();
00553 return COLVARS_OK;
00554 )
00555 
00556 CVSCRIPT(cv_save,
00557 "Change the prefix of all output files and save them",
00558 1, 1,
00559 "prefix : string - Output prefix with trailing \".colvars.state\" gets removed)",
00560 std::string const prefix =
00561 cvm::state_file_prefix(script->obj_to_str(script->get_module_cmd_arg(0, objc, objv)));
00562 script->proxy()->output_prefix() = prefix;
00563 int error_code = COLVARS_OK;
00564 error_code |= script->module()->setup_output();
00565 error_code |= script->module()->write_restart_file(prefix+
00566 ".colvars.state");
00567 error_code |= script->module()->write_output_files();
00568 return error_code;
00569 )
00570 
00571 CVSCRIPT(cv_savetostring,
00572 "Write the Colvars state to a string and return it\n"
00573 "state : string - The saved state",
00574 0, 0,
00575 "",
00576 return script->module()->write_restart_string(script->modify_str_result());
00577 )
00578 
00579 CVSCRIPT(cv_targettemperature,
00580 "Get/set target temperature, overriding what the MD engine provides\n"
00581 "T : float - Current target temperature in K",
00582 0, 1,
00583 "T : float - New target temperature in K",
00584 char const *Targ =
00585 script->obj_to_str(script->get_module_cmd_arg(0, objc, objv));
00586 if (Targ == NULL) {
00587 return script->set_result_real(script->proxy()->target_temperature());
00588 } else {
00589 return script->proxy()->set_target_temperature(strtod(Targ, NULL));
00590 }
00591 )
00592 
00593 CVSCRIPT(cv_units,
00594 "Get or set the current Colvars unit system\n"
00595 "units : string - The current unit system",
00596 0, 1,
00597 "units : string - The new unit system",
00598 char const *argstr =
00599 script->obj_to_str(script->get_module_cmd_arg(0, objc, objv));
00600 if (argstr) {
00601 return cvm::proxy->set_unit_system(argstr, false);
00602 } else {
00603 script->set_result_str(cvm::proxy->units);
00604 return COLVARS_OK;
00605 }
00606 )
00607 
00608 CVSCRIPT(cv_update,
00609 "Recalculate colvars and biases",
00610 0, 0,
00611 "",
00612 int error_code = script->proxy()->update_input();
00613 if (error_code) {
00614 script->add_error_msg("Error updating the Colvars module (input)");
00615 return error_code;
00616 }
00617 error_code |= script->module()->calc();
00618 if (error_code) {
00619 script->add_error_msg("Error updating the Colvars module (calc)");
00620 return error_code;
00621 }
00622 error_code |= script->proxy()->update_output();
00623 if (error_code) {
00624 script->add_error_msg("Error updating the Colvars module (output)");
00625 }
00626 return error_code;
00627 )
00628 
00629 CVSCRIPT(cv_version,
00630 "Get the Colvars Module version string\n"
00631 "version : string - Colvars version",
00632 0, 0,
00633 "",
00634 script->set_result_str(COLVARS_VERSION);
00635 return COLVARS_OK;
00636 )
00637 
00638 // This guard allows compiling colvar and bias function bodies in their
00639 // respecitve files instead of colvarscript_commands.o
00640 #ifndef COLVARSCRIPT_COMMANDS_GLOBAL
00641 #include "colvarscript_commands_colvar.h"
00642 #include "colvarscript_commands_bias.h"
00643 #endif
00644 
00645 #endif // #ifndef COLVARSCRIPT_COMMANDS_H