Main Page   Namespace List   Class Hierarchy   Alphabetical List   Compound List   File List   Namespace Members   Compound Members   File Members   Related Pages  

colvarscript_commands.h

Go to the documentation of this file.
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

Generated on Fri Oct 4 02:43:47 2024 for VMD (current) by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002