Collective Variables Module - Developer Documentation
Loading...
Searching...
No Matches
colvarscript_commands.h
1// -*- c++ -*-
2
3// This file is part of the Collective Variables module (Colvars).
4// The original version of Colvars and its updates are located at:
5// https://github.com/Colvars/colvars
6// Please update all Colvars source files before making any changes.
7// If you wish to distribute your changes, please submit them to the
8// Colvars repository at GitHub.
9
10#ifndef COLVARSCRIPT_COMMANDS_H
11#define COLVARSCRIPT_COMMANDS_H
12
13// The following is a complete definition of the scripting API.
14
15// The CVSCRIPT macro is used in four distinct contexts:
16// 1) Expand to the functions' prototypes (when included generically)
17// 2) List colvarscript::command entries (when included in colvarscript.h)
18// 3) Implement colvarscript::init() (when included in colvarscript.cpp)
19// 4) Define the functions' bodies (when included in colvarscript_commands.cpp)
20
21
22// Each command is created by an instance of the CVSCRIPT macro
23
24// The arguments of the CVSCRIPT macro are:
25
26// COMM = the id of the command (must be a member of colvarscript::command)
27
28// HELP = short description (C string literal) for the command; the second line
29// is optional, and documents the return value (if any)
30
31// N_ARGS_MIN = the lowest number of arguments allowed
32
33// N_ARGS_MAX = the highest number of arguments allowed
34
35// ARGS = multi-line string literal describing each parameter; each line
36// follows the format "name : type - description"
37
38// FN_BODY = the implementation of the function; this should be a thin wrapper
39// over existing functions; the "script" pointer to the colvarscript
40// object is already set by the CVSCRIPT_COMM_FN macro; see also the
41// functions in colvarscript_commands.h.
42
43#ifndef CVSCRIPT_COMM_FNAME
44#define CVSCRIPT_COMM_FNAME(COMM) cvscript_ ## COMM
45#endif
46
47// If CVSCRIPT is not defined, this file yields the function prototypes
48#ifndef CVSCRIPT
49
50#define CVSCRIPT_COMM_PROTO(COMM) \
51 extern "C" int CVSCRIPT_COMM_FNAME(COMM)(void *, \
52 int, \
53 unsigned char *const *);
54
55#define CVSCRIPT(COMM,HELP,N_ARGS_MIN,N_ARGS_MAX,ARGS,FN_BODY) \
56 CVSCRIPT_COMM_PROTO(COMM)
57
58
59// Utility functions used to query the command database
60extern "C" {
61
63 int cvscript_n_commands();
64
66 char const ** cvscript_command_names();
67
70 char const *cvscript_command_help(char const *cmd);
71
74 char const *cvscript_command_rethelp(char const *cmd);
75
81 char const *cvscript_command_arghelp(char const *cmd, int i);
82
85 char const *cvscript_command_full_help(char const *cmd);
86
89 int cvscript_command_n_args_min(char const *cmd);
90
93 int cvscript_command_n_args_max(char const *cmd);
94
95}
96
97#endif
98
99
100CVSCRIPT(cv_addenergy,
101 "Add an energy to the MD engine (no effect in VMD)",
102 1, 1,
103 "E : float - Amount of energy to add",
104 char const *Earg =
105 script->obj_to_str(script->get_module_cmd_arg(0, objc, objv));
106 cvm::main()->total_bias_energy += strtod(Earg, NULL);
107 return cvm::get_error(); // TODO Make this multi-language
108 )
109
110CVSCRIPT(cv_bias,
111 "Prefix for bias-specific commands",
112 0, 0,
113 "",
114 // This cannot be executed from a command line
115 return COLVARS_OK;
116 )
117
118CVSCRIPT(cv_colvar,
119 "Prefix for colvar-specific commands",
120 0, 0,
121 "",
122 // This cannot be executed from a command line
123 return COLVARS_OK;
124 )
125
126CVSCRIPT(cv_config,
127 "Read configuration from the given string",
128 1, 1,
129 "conf : string - Configuration string",
130 char const *conf_str =
131 script->obj_to_str(script->get_module_cmd_arg(0, objc, objv));
132 std::string const conf(conf_str);
133 script->proxy()->add_config("config", conf);
134 if (script->proxy()->engine_ready()) {
135 // Engine allows immediate initialization
136 if ((script->proxy()->parse_module_config() |
137 script->proxy()->setup()) == COLVARS_OK) {
138 return COLVARS_OK;
139 } else {
140 script->add_error_msg("Error parsing configuration string");
141 return COLVARSCRIPT_ERROR;
142 }
143 }
144 // Engine not ready, config will be read during proxy->setup()
145 return COLVARS_OK;
146 )
147
148CVSCRIPT(cv_configfile,
149 "Read configuration from a file",
150 1, 1,
151 "conf_file : string - Path to configuration file",
152 char const *conf_file_name =
153 script->obj_to_str(script->get_module_cmd_arg(0, objc, objv));
154 script->proxy()->add_config("configfile", std::string(conf_file_name));
155 if (script->proxy()->engine_ready()) {
156 // Engine allows immediate initialization
157 if ((script->proxy()->parse_module_config() |
158 script->proxy()->setup()) == COLVARS_OK) {
159 return COLVARS_OK;
160 } else {
161 script->add_error_msg("Error parsing configuration file");
162 return COLVARSCRIPT_ERROR;
163 }
164 }
165 // Engine not ready, config will be read during proxy->setup()
166 return COLVARS_OK;
167 )
168
169CVSCRIPT(cv_delete,
170 "Delete this Colvars module instance (VMD only)",
171 0, 0,
172 "",
173 return script->proxy()->request_deletion();
174 )
175
176CVSCRIPT(cv_featurereport,
177 "Return a summary of Colvars features used so far and their citations\n"
178 "report : string - Feature report and citations",
179 0, 0,
180 "",
181 return script->set_result_str(script->module()->feature_report());
182 )
183
184CVSCRIPT(cv_frame,
185 "Get or set current frame number (VMD only)\n"
186 "frame : integer - Frame number",
187 0, 1,
188 "frame : integer - Frame number",
189 char const *arg =
190 script->obj_to_str(script->get_module_cmd_arg(0, objc, objv));
191 if (arg == NULL) {
192 long int f = -1;
193 if (script->proxy()->get_frame(f) == COLVARS_OK) {
194 script->set_result_long_int(f);
195 return COLVARS_OK;
196 } else {
197 script->add_error_msg("Frame number is not available");
198 return COLVARSCRIPT_ERROR;
199 }
200 } else {
201 int const f = strtol(const_cast<char *>(arg), NULL, 10);
202 int error_code = script->proxy()->set_frame(f);
203 if (error_code == COLVARS_NO_SUCH_FRAME) {
204 script->add_error_msg("Invalid frame number: \""+std::string(arg)+
205 "\"\n");
206 }
207 return error_code;
208 }
209 return COLVARS_OK;
210 )
211
212CVSCRIPT(cv_getatomappliedforces,
213 "Get the list of forces applied by Colvars to atoms\n"
214 "forces : array of arrays of floats - Atomic forces",
215 0, 0,
216 "",
217 script->set_result_rvector_vec(*(script->proxy()->get_atom_applied_forces()));
218 return COLVARS_OK;
219 )
220
221CVSCRIPT(cv_getatomappliedforcesmax,
222 "Get the maximum norm of forces applied by Colvars to atoms\n"
223 "force : float - Maximum atomic force",
224 0, 0,
225 "",
226 script->set_result_real(script->proxy()->max_atoms_applied_force());
227 return COLVARS_OK;
228 )
229
230CVSCRIPT(cv_getatomappliedforcesmaxid,
231 "Get the atom ID with the largest applied force\n"
232 "id : int - ID of the atom with the maximum atomic force",
233 0, 0,
234 "",
235 script->set_result_int(script->proxy()->max_atoms_applied_force_id());
236 return COLVARS_OK;
237 )
238
239CVSCRIPT(cv_getatomappliedforcesrms,
240 "Get the root-mean-square norm of forces applied by Colvars to atoms\n"
241 "force : float - RMS atomic force",
242 0, 0,
243 "",
244 script->set_result_real(script->proxy()->rms_atoms_applied_force());
245 return COLVARS_OK;
246 )
247
248CVSCRIPT(cv_resetatomappliedforces,
249 "Reset forces applied by Colvars to atoms",
250 0, 0,
251 "",
252 size_t i;
253 std::vector<cvm::rvector> *f = script->proxy()->modify_atom_applied_forces();
254 for (i = 0; i < f->size(); i++) {
255 (*f)[i].reset();
256 }
257 return COLVARS_OK;
258 )
259
260CVSCRIPT(cv_getatomids,
261 "Get the list of indices of atoms used in Colvars\n"
262 "indices : array of ints - Atom indices",
263 0, 0,
264 "",
265 script->set_result_int_vec(*(script->proxy()->get_atom_ids()));
266 return COLVARS_OK;
267 )
268
269CVSCRIPT(cv_getatomcharges,
270 "Get the list of charges of atoms used in Colvars\n"
271 "charges : array of floats - Atomic charges",
272 0, 0,
273 "",
274 script->set_result_real_vec(*(script->proxy()->get_atom_charges()));
275 return COLVARS_OK;
276 )
277
278CVSCRIPT(cv_getatommasses,
279 "Get the list of masses of atoms used in Colvars\n"
280 "masses : array of floats - Atomic masses",
281 0, 0,
282 "",
283 script->set_result_real_vec(*(script->proxy()->get_atom_masses()));
284 return COLVARS_OK;
285 )
286
287CVSCRIPT(cv_getatompositions,
288 "Get the list of cached positions of atoms used in Colvars\n"
289 "positions : array of arrays of floats - Atomic positions",
290 0, 0,
291 "",
292 script->set_result_rvector_vec(*(script->proxy()->get_atom_positions()));
293 return COLVARS_OK;
294 )
295
296CVSCRIPT(cv_getatomtotalforces,
297 "Get the list of cached total forces of atoms used in Colvars\n"
298 "forces : array of arrays of floats - Atomic total foces",
299 0, 0,
300 "",
301 script->set_result_rvector_vec(*(script->proxy()->get_atom_total_forces()));
302 return COLVARS_OK;
303 )
304
305CVSCRIPT(cv_getconfig,
306 "Get the module's configuration string read so far\n"
307 "conf : string - Current configuration string",
308 0, 0,
309 "",
310 script->set_result_str(cvm::main()->get_config());
311 return COLVARS_OK;
312 )
313
314CVSCRIPT(cv_getenergy,
315 "Get the current Colvars energy\n"
316 "E : float - Amount of energy (internal units)",
317 0, 0,
318 "",
319 script->set_result_real(cvm::main()->total_bias_energy);
320 return COLVARS_OK;
321 )
322
323CVSCRIPT(cv_getnumactiveatomgroups,
324 "Get the number of atom groups that currently have positive ref counts\n"
325 "count : integer - Total number of atom groups",
326 0, 0,
327 "",
328 script->set_result_int(static_cast<int>(script->proxy()->get_num_active_atom_groups()));
329 return COLVARS_OK;
330 )
331
332CVSCRIPT(cv_getnumactiveatoms,
333 "Get the number of atoms that currently have positive ref counts\n"
334 "count : integer - Total number of atoms",
335 0, 0,
336 "",
337 script->set_result_int(static_cast<int>(script->proxy()->get_num_active_atoms()));
338 return COLVARS_OK;
339 )
340
341CVSCRIPT(cv_getnumatoms,
342 "Get the number of requested atoms, including those not in use now\n"
343 "count : integer - Total number of atoms",
344 0, 0,
345 "",
346 script->set_result_int(static_cast<int>(script->proxy()->get_atom_ids()->size()));
347 return COLVARS_OK;
348 )
349
350CVSCRIPT(cv_getstepabsolute,
351 "Get the current step number of the simulation (including restarts)\n"
352 "step : int - Absolute step number",
353 0, 0,
354 "",
355 script->set_result_int(cvm::step_absolute());
356 return COLVARS_OK;
357 )
358
359CVSCRIPT(cv_getsteprelative,
360 "Get the current step number from the start of this job\n"
361 "step : int - Relative step number",
362 0, 0,
363 "",
364 script->set_result_int(cvm::step_relative());
365 return COLVARS_OK;
366 )
367
368CVSCRIPT(cv_help,
369 "Get the help string of the Colvars scripting interface\n"
370 "help : string - Help string",
371 0, 1,
372 "command : string - Get the help string of this specific command",
373 unsigned char *const cmdobj =
374 script->get_module_cmd_arg(0, objc, objv);
375 if (cmdobj) {
376 std::string const cmdstr(script->obj_to_str(cmdobj));
377 if (cmdstr.size()) {
378 if (cmdstr == std::string("colvar")) {
379 script->set_result_str(script->get_cmdline_help_summary(colvarscript::use_colvar));
380 } else if (cmdstr == std::string("bias")) {
381 script->set_result_str(script->get_cmdline_help_summary(colvarscript::use_bias));
382 } else {
383 script->set_result_str(script->get_command_cmdline_help(colvarscript::use_module,
384 cmdstr));
385 }
386 return cvm::get_error();
387 } else {
388 return COLVARSCRIPT_ERROR;
389 }
390 } else {
391 script->set_result_str(script->get_cmdline_help_summary(colvarscript::use_module));
392 return COLVARS_OK;
393 }
394 )
395
396CVSCRIPT(cv_languageversion,
397 "Get the C++ language version number\n"
398 "version : string - C++ language version",
399 0, 0,
400 "",
401 script->set_result_int(__cplusplus);
402 return COLVARS_OK;
403 )
404
405CVSCRIPT(cv_list,
406 "Return a list of all variables or biases\n"
407 "list : sequence of strings - List of elements",
408 0, 1,
409 "param : string - \"colvars\" or \"biases\"; default is \"colvars\"",
410 std::string res;
411 unsigned char *const kwarg = script->get_module_cmd_arg(0, objc, objv);
412 std::string const kwstr = kwarg ? script->obj_to_str(kwarg) :
413 std::string("colvars");
414 if (kwstr == "colvars") {
415 for (std::vector<colvar *>::iterator cvi = script->module()->variables()->begin();
416 cvi != script->module()->variables()->end();
417 ++cvi) {
418 res += (cvi == script->module()->variables()->begin() ? "" : " ") + (*cvi)->name;
419 }
420 script->set_result_str(res);
421 return COLVARS_OK;
422 } else if (kwstr == "biases") {
423 for (std::vector<colvarbias *>::iterator bi = script->module()->biases.begin();
424 bi != script->module()->biases.end();
425 ++bi) {
426 res += (bi == script->module()->biases.begin() ? "" : " ") + (*bi)->name;
427 }
428 script->set_result_str(res);
429 return COLVARS_OK;
430 } else {
431 script->add_error_msg("Wrong arguments to command \"list\"\n");
432 return COLVARSCRIPT_ERROR;
433 }
434 )
435
436CVSCRIPT(cv_listcommands,
437 "Get the list of script functions, prefixed with \"cv_\", \"colvar_\" or \"bias_\"\n"
438 "list : sequence of strings - List of commands",
439 0, 0,
440 "",
441 int const n_commands = cvscript_n_commands();
442 char const **command_names = cvscript_command_names();
443 std::string result;
444 for (int i = 0; i < n_commands; i++) {
445 if (i > 0) result.append(1, ' ');
446 result.append(std::string(command_names[i]));
447 }
448 script->set_result_str(result);
449 return COLVARS_OK;
450 )
451
452CVSCRIPT(cv_listindexfiles,
453 "Get a list of the index files loaded in this session\n"
454 "list : sequence of strings - List of index file names",
455 0, 0,
456 "",
457 int const n_files = script->module()->index_file_names.size();
458 std::string result;
459 for (int i = 0; i < n_files; i++) {
460 if (i > 0) result.append(1, ' ');
461 result.append(script->module()->index_file_names[i]);
462 }
463 script->set_result_str(result);
464 return COLVARS_OK;
465 )
466
467CVSCRIPT(cv_listinputfiles,
468 "Get a list of all input/configuration files loaded in this session\n"
469 "list : sequence of strings - List of file names",
470 0, 0,
471 "",
472 std::list<std::string> const l =
473 script->proxy()->list_input_stream_names();
474 std::string result;
475 for (std::list<std::string>::const_iterator li = l.begin();
476 li != l.end(); li++) {
477 if (li != l.begin()) result.append(1, ' ');
478 result.append(*li);
479 }
480 script->set_result_str(result);
481 return COLVARS_OK;
482 )
483
484CVSCRIPT(cv_load,
485 "Load data from a state file into all matching colvars and biases",
486 1, 1,
487 "prefix : string - Path to existing state file or input prefix",
488 char const *arg =
489 script->obj_to_str(script->get_module_cmd_arg(0, objc, objv));
490 int error_code =
491 script->proxy()->set_input_prefix(cvm::state_file_prefix(arg));
492 error_code |= script->module()->setup_input();
493 if (error_code != COLVARS_OK) {
494 script->add_error_msg("Error loading state file");
495 }
496 return error_code;
497 )
498
499CVSCRIPT(cv_loadfromstring,
500 "Load state data from a string into all matching colvars and biases",
501 1, 1,
502 "buffer : string - String buffer containing the state information",
503 char const *arg =
504 script->obj_to_str(script->get_module_cmd_arg(0, objc, objv));
505 script->proxy()->input_stream_from_string("input state string",
506 std::string(arg));
507 if (script->module()->setup_input() == COLVARS_OK) {
508 return COLVARS_OK;
509 } else {
510 script->add_error_msg("Error loading state string");
511 return COLVARSCRIPT_ERROR;
512 }
513 )
514
515CVSCRIPT(cv_molid,
516 "Get or set the molecule ID on which Colvars is defined (VMD only)\n"
517 "molid : integer - Current molecule ID",
518 0, 1,
519 "molid : integer - New molecule ID; -1 means undefined",
520 char const *arg =
521 script->obj_to_str(script->get_module_cmd_arg(0, objc, objv));
522 if (arg == NULL) {
523 int molid = -1;
524 script->proxy()->get_molid(molid);
525 script->set_result_int(molid);
526 return COLVARS_OK;
527 } else {
528 script->add_error_msg("Error: To change the molecule ID in VMD, use cv delete first.");
529 return COLVARS_NOT_IMPLEMENTED;
530 }
531 )
532
533CVSCRIPT(cv_printframe,
534 "Return the values that would be written to colvars.traj\n"
535 "values : string - The values\n",
536 0, 0,
537 "",
538 std::ostringstream os;
539 script->module()->write_traj(os);
540 script->set_result_str(os.str());
541 return COLVARS_OK;
542 )
543
544CVSCRIPT(cv_printframelabels,
545 "Return the labels that would be written to colvars.traj\n"
546 "Labels : string - The labels",
547 0, 0,
548 "",
549 std::ostringstream os;
550 script->module()->write_traj_label(os);
551 script->set_result_str(os.str());
552 return COLVARS_OK;
553 )
554
555CVSCRIPT(cv_reset,
556 "Delete all internal configuration",
557 0, 0,
558 "",
559 cvm::log("Resetting the Collective Variables module.");
560 return script->module()->reset();
561 )
562
563CVSCRIPT(cv_resetindexgroups,
564 "Clear the index groups loaded so far, allowing to replace them",
565 0, 0,
566 "",
567 cvm::main()->index_group_names.clear();
568 cvm::main()->index_groups.clear();
569 return COLVARS_OK;
570 )
571
572CVSCRIPT(cv_save,
573 "Change the prefix of all output files and save them",
574 1, 1,
575 "prefix : string - Output prefix with trailing \".colvars.state\" gets removed)",
576 std::string const prefix =
577 cvm::state_file_prefix(script->obj_to_str(script->get_module_cmd_arg(0, objc, objv)));
578 int error_code = script->proxy()->set_output_prefix(prefix);
579 error_code |= script->module()->setup_output();
580 error_code |= script->module()->write_restart_file(prefix+
581 ".colvars.state");
582 error_code |= script->module()->write_output_files();
583 return error_code;
584 )
585
586CVSCRIPT(cv_savetostring,
587 "Write the Colvars state to a string and return it\n"
588 "state : string - The saved state",
589 0, 0,
590 "",
591 return script->module()->write_restart_string(script->modify_str_result());
592 )
593
594CVSCRIPT(cv_targettemperature,
595 "Get/set target temperature, overriding internally what the MD engine reports\n"
596 "T : float - Current target temperature in K",
597 0, 1,
598 "T : float - New target temperature in K (internal use)",
599 char const *Targ =
600 script->obj_to_str(script->get_module_cmd_arg(0, objc, objv));
601 if (Targ == NULL) {
602 return script->set_result_real(script->proxy()->target_temperature());
603 } else {
604 return script->proxy()->set_target_temperature(strtod(Targ, NULL));
605 }
606 )
607
608CVSCRIPT(cv_timestep,
609 "Get/set integration timestep, overriding internally what the MD engine reports\n"
610 "dt : float - Current integration timestep in MD engine units",
611 0, 1,
612 "dt : float - New integration timestep in MD engine units",
613 char const *arg =
614 script->obj_to_str(script->get_module_cmd_arg(0, objc, objv));
615 if (arg == NULL) {
616 return script->set_result_real(script->proxy()->dt());
617 } else {
618 return script->proxy()->set_integration_timestep(strtod(arg, NULL));
619 }
620 )
621
622CVSCRIPT(cv_units,
623 "Get or set the current Colvars unit system\n"
624 "units : string - The current unit system",
625 0, 1,
626 "units : string - The new unit system",
627 char const *argstr =
628 script->obj_to_str(script->get_module_cmd_arg(0, objc, objv));
629 if (argstr) {
630 return cvm::proxy->set_unit_system(argstr, false);
631 } else {
632 script->set_result_str(cvm::proxy->units);
633 return COLVARS_OK;
634 }
635 )
636
637CVSCRIPT(cv_update,
638 "Recalculate colvars and biases",
639 0, 0,
640 "",
641 int error_code = script->proxy()->update_input();
642 if (error_code) {
643 script->add_error_msg("Error updating the Colvars module (input)");
644 return error_code;
645 }
646 error_code |= script->module()->calc();
647 if (error_code) {
648 script->add_error_msg("Error updating the Colvars module (calc)");
649 return error_code;
650 }
651 error_code |= script->proxy()->update_output();
652 if (error_code) {
653 script->add_error_msg("Error updating the Colvars module (output)");
654 }
655 return error_code;
656 )
657
658CVSCRIPT(cv_version,
659 "Get the Colvars Module version string\n"
660 "version : string - Colvars version",
661 0, 0,
662 "",
663 script->set_result_str(COLVARS_VERSION);
664 return COLVARS_OK;
665 )
666
667// This guard allows compiling colvar and bias function bodies in their
668// respecitve files instead of colvarscript_commands.o
669#ifndef COLVARSCRIPT_COMMANDS_GLOBAL
670#include "colvarscript_commands_colvar.h"
671#include "colvarscript_commands_bias.h"
672#endif
673
674#endif // #ifndef COLVARSCRIPT_COMMANDS_H
static std::string state_file_prefix(char const *filename)
Strips .colvars.state from filename and checks that it is not empty.
Definition: colvarmodule.cpp:1510
std::vector< std::string > index_group_names
Names of groups from one or more Gromacs .ndx files.
Definition: colvarmodule.h:749
std::vector< std::vector< int > * > index_groups
Groups from one or more Gromacs .ndx files.
Definition: colvarmodule.h:752
real total_bias_energy
Energy of built-in and scripted biases, summed per time-step.
Definition: colvarmodule.h:314
static void log(std::string const &message, int min_log_level=10)
Definition: colvarmodule.cpp:1955
std::string const & get_config() const
Get the configuration string read so far (includes comments)
Definition: colvarmodule.cpp:347
static colvarmodule * main()
Access the one instance of the Colvars module.
Definition: colvarmodule.cpp:174
static step_number step_relative()
Return the current step number from the beginning of this run.
Definition: colvarmodule.h:233
static colvarproxy * proxy
Pointer to the proxy object, used to retrieve atomic data from the hosting program; it is static in o...
Definition: colvarmodule.h:860
static step_number step_absolute()
Definition: colvarmodule.h:240
virtual int set_unit_system(std::string const &units, bool check_only)
Request to set the units used internally by Colvars.
Definition: colvarproxy_system.cpp:36