Collective Variables Module - Developer Documentation
colvarscript.h
1 // -*- c++ -*-
2 
3 #ifndef COLVARSCRIPT_H
4 //#define COLVARSCRIPT_H // Delay definition until later
5 
6 #include <string>
7 #include <vector>
8 #include <map>
9 
10 #include "colvarmodule.h"
11 #include "colvarvalue.h"
12 #include "colvarbias.h"
13 #include "colvarproxy.h"
14 
15 
16 // Only these error values are part of the scripting interface
17 #define COLVARSCRIPT_ERROR -1
18 #define COLVARSCRIPT_OK 0
19 
20 
21 class colvarscript {
22 
23 private:
24 
25  colvarproxy *proxy;
26  colvarmodule *colvars;
27 
28  inline colvarscript() {} // no-argument construction forbidden
29 
30 public:
31 
32  friend class colvarproxy;
33 
35  inline ~colvarscript() {}
36 
40 
43  std::string result;
44 
46  int run(int objc, unsigned char *const objv[]);
47 
49  inline void set_str_result(std::string const &s)
50  {
51  result = s;
52  }
53 
55  std::string help_string(void) const;
56 
58  inline char const *obj_to_str(unsigned char *const obj)
59  {
60  return cvm::proxy->script_obj_to_str(obj);
61  }
62 
63  enum command {
64  cv_help,
65  cv_version,
66  cv_config,
67  cv_configfile,
68  cv_reset,
69  cv_delete,
70  cv_list,
71  cv_list_biases,
72  cv_load,
73  cv_save,
74  cv_update,
75  cv_addenergy,
76  cv_getenergy,
77  cv_printframe,
78  cv_printframelabels,
79  cv_frame,
80  cv_colvar,
81  cv_colvar_value,
82  cv_colvar_update,
83  cv_colvar_type,
84  cv_colvar_delete,
85  cv_colvar_addforce,
86  cv_colvar_getappliedforce,
87  cv_colvar_gettotalforce,
88  cv_colvar_cvcflags,
89  cv_colvar_getconfig,
90  cv_colvar_get,
91  cv_colvar_set,
92  cv_bias,
93  cv_bias_energy,
94  cv_bias_update,
95  cv_bias_delete,
96  cv_bias_getconfig,
97  cv_bias_get,
98  cv_bias_set,
99  cv_n_commands
100  };
101 
103  inline int exec_command(command c,
104  void *pobj,
105  int objc, unsigned char * const *objv)
106  {
107  return (*(comm_fns[c]))(pobj, objc, objv);
108  }
109 
111  inline std::string command_help(colvarscript::command c) const
112  {
113  return comm_help[c];
114  }
115 
117  inline void clear_results()
118  {
119  result.clear();
120  }
121 
122 private:
123 
125  int proc_colvar(colvar *cv, int argc, unsigned char *const argv[]);
126 
128  int proc_bias(colvarbias *b, int argc, unsigned char *const argv[]);
129 
131  int proc_features(colvardeps *obj,
132  int argc, unsigned char *const argv[]);
133 
135  std::map<std::string, command> comm_str_map;
136 
138  std::vector<std::string> comm_help;
139 
141  std::vector<size_t> comm_n_args;
142 
144  std::vector< std::vector<std::string> > comm_args;
145 
147  std::vector<int (*)(void *, int, unsigned char * const *)> comm_fns;
148 
149 };
150 
151 
153 inline static colvarscript *colvarscript_obj()
154 {
155  return cvm::main()->proxy->script;
156 }
157 
159 inline static colvar *colvar_obj(void *pobj)
160 {
161  return reinterpret_cast<colvar *>(pobj);
162 }
163 
165 inline static colvarbias *colvarbias_obj(void *pobj)
166 {
167  return reinterpret_cast<colvarbias *>(pobj);
168 }
169 
170 
171 #define CVSCRIPT_COMM_FNAME(COMM) cvscript_ ## COMM
172 
173 #define CVSCRIPT_COMM_PROTO(COMM) \
174  int CVSCRIPT_COMM_FNAME(COMM)(void *, int, unsigned char *const *);
175 
176 #define CVSCRIPT(COMM,HELP,N_ARGS_MIN,N_ARGS_MAX,ARGS,FN_BODY) \
177  CVSCRIPT_COMM_PROTO(COMM)
178 
179 #undef COLVARSCRIPT_H
180 #endif // #ifndef COLVARSCRIPT_H
181 
182 
183 #ifdef COLVARSCRIPT_CPP
184 #define CVSCRIPT_COMM_FN(COMM,N_ARGS_MIN,N_ARGS_MAX,ARGS,FN_BODY) \
185  int CVSCRIPT_COMM_FNAME(COMM)(void *pobj, \
186  int objc, unsigned char *const objv[]) \
187  { \
188  colvarscript *script = colvarscript_obj(); \
189  script->clear_results(); \
190  if (objc < 2+N_ARGS_MIN) /* "cv" and "COMM" are 1st and 2nd */ { \
191  script->set_str_result("Missing arguments\n" + \
192  script->command_help(colvarscript::COMM)); \
193  return COLVARSCRIPT_ERROR; \
194  } \
195  if (objc > 2+N_ARGS_MAX) { \
196  script->set_str_result("Too many arguments\n" + \
197  script->command_help(colvarscript::COMM)); \
198  return COLVARSCRIPT_ERROR; \
199  } \
200  FN_BODY; \
201  }
202 #undef CVSCRIPT
203 #define CVSCRIPT(COMM,HELP,N_ARGS_MIN,N_ARGS_MAX,ARGS,FN_BODY) \
204  CVSCRIPT_COMM_FN(COMM,N_ARGS_MIN,N_ARGS_MAX,ARGS,FN_BODY)
205 #endif // #ifdef COLVARSCRIPT_CPP
206 
207 
208 #ifdef COLVARSCRIPT_INIT_FN
209 #define CVSCRIPT_COMM_INIT(COMM,HELP,ARGS) { \
210  comm_str_map[#COMM] = COMM; \
211  comm_help[COMM] = HELP; \
212  comm_fns[COMM] = &(CVSCRIPT_COMM_FNAME(COMM)); \
213  }
214 #undef CVSCRIPT
215 #define CVSCRIPT(COMM,HELP,N_ARGS_MIN,N_ARGS_MAX,ARGS,FN_BODY) \
216  CVSCRIPT_COMM_INIT(COMM,HELP,ARGS)
217 #endif
218 
219 
220 #if !defined(COLVARSCRIPT_H) || defined(COLVARSCRIPT_INIT_FN)
221 #define COLVARSCRIPT_H
222 
223 #ifndef COLVARSCRIPT_INIT_FN
224 #ifdef __cplusplus
225 extern "C" {
226 #endif
227 #endif
228 
229  // Add optional arguments for command-specific help?
230  CVSCRIPT(cv_help,
231  "Print the help message",
232  0, 0,
233  {},
235  return COLVARS_OK;
236  )
237 
238  CVSCRIPT(cv_config,
239  "Read configuration from the given string",
240  1, 1,
241  { "conf (str) - Configuration string" },
242  std::string const conf(script->obj_to_str(objv[2]));
243  if (cvm::main()->read_config_string(conf) == COLVARS_OK) {
244  return COLVARS_OK;
245  }
246  script->set_str_result("Error parsing configuration string");
247  return COLVARSCRIPT_ERROR;
248  )
249 
250  CVSCRIPT(cv_addenergy,
251  "Add an energy to the MD engine",
252  1, 1,
253  { "E (float) - Amount of energy to add" },
255  strtod(script->obj_to_str(objv[2]), NULL);
256  return COLVARS_OK;
257  )
258 
259  CVSCRIPT(cv_getenergy,
260  "Get the current Colvars energy",
261  1, 1,
262  { "E (float) - Store the energy in this variable" },
263  double *energy = reinterpret_cast<double *>(objv[2]);
264  *energy = cvm::main()->total_bias_energy;
265  return COLVARS_OK;
266  )
267 
268 #ifndef COLVARSCRIPT_INIT_FN
269 #ifdef __cplusplus
270 } // extern "C"
271 #endif
272 #endif
273 
274 #undef CVSCRIPT
275 
276 #endif // #ifndef COLVARSCRIPT_H
void clear_results()
Clear all object results.
Definition: colvarscript.h:117
char const * obj_to_str(unsigned char *const obj)
Use scripting language to get the string representation of an object.
Definition: colvarscript.h:58
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:590
Collective variables module (main class)
Definition: colvarmodule.h:62
virtual char * script_obj_to_str(unsigned char *obj)
Convert a script object (Tcl or Python call argument) to a C string.
Definition: colvarproxy.cpp:416
real total_bias_energy
Energy of built-in and scripted biases, summed per time-step.
Definition: colvarmodule.h:224
int run(int objc, unsigned char *const objv[])
Run script command with given positional arguments (objects)
Definition: colvarscript.cpp:58
Colvars proxy classes.
Interface between the collective variables module and the simulation or analysis program (NAMD...
Definition: colvarproxy.h:529
int exec_command(command c, void *pobj, int objc, unsigned char *const *objv)
Execute a script command.
Definition: colvarscript.h:103
Collective variables main module.
Collective variable bias, base class.
Definition: colvarbias.h:12
int proxy_error
Definition: colvarscript.h:39
Definition: colvarscript.h:21
colvarscript * script
Definition: colvarproxy.h:427
Parent class for a member object of a bias, cv or cvc etc. containing features and their dependencies...
Definition: colvardeps.h:23
A collective variable (main class); to be defined, it needs at least one object of a derived class of...
Definition: colvar.h:42
int read_config_string(std::string const &conf)
Parse a config string assuming it is a complete configuration (i.e. calling all parse functions) ...
Definition: colvarmodule.cpp:144
static colvarmodule * main()
Access the one instance of the Colvars module.
Definition: colvarmodule.cpp:73
std::string help_string(void) const
Build and return a short help.
Definition: colvarscript.cpp:530
std::string result
Definition: colvarscript.h:43
std::string command_help(colvarscript::command c) const
Get help for a command (TODO reformat for each language?)
Definition: colvarscript.h:111
void set_str_result(std::string const &s)
Set the return value of the script command to the given string.
Definition: colvarscript.h:49