Line data Source code
1 : /* +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
2 : Copyright (c) 2019-2023 The plumed team
3 : (see the PEOPLE file at the root of the distribution for a list of names)
4 :
5 : See http://www.plumed.org for more information.
6 :
7 : This file is part of plumed, version 2.
8 :
9 : plumed is free software: you can redistribute it and/or modify
10 : it under the terms of the GNU Lesser General Public License as published by
11 : the Free Software Foundation, either version 3 of the License, or
12 : (at your option) any later version.
13 :
14 : plumed is distributed in the hope that it will be useful,
15 : but WITHOUT ANY WARRANTY; without even the implied warranty of
16 : MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 : GNU Lesser General Public License for more details.
18 :
19 : You should have received a copy of the GNU Lesser General Public License
20 : along with plumed. If not, see <http://www.gnu.org/licenses/>.
21 : +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ */
22 : #include "CLTool.h"
23 : #include "core/CLToolRegister.h"
24 : #include "tools/Tools.h"
25 : #include "config/Config.h"
26 : #include "core/ActionRegister.h"
27 : #include "core/ActionWithValue.h"
28 : #include "core/ActionWithVirtualAtom.h"
29 : #include "core/ActionShortcut.h"
30 : #include "core/ActionSet.h"
31 : #include "core/PlumedMain.h"
32 : #include "tools/Communicator.h"
33 : #include "tools/IFile.h"
34 : #include <cstdio>
35 : #include <string>
36 : #include <vector>
37 : #include <iostream>
38 : #include <fstream>
39 :
40 : namespace PLMD {
41 : namespace cltools {
42 :
43 : //+PLUMEDOC TOOLS gen_example
44 : /*
45 : gen_example is a tool that you can use to construct an example for the manual that users can interact with to understand
46 :
47 : The example constructed by this action is in html. In all probability you will never need to use this
48 : tool. However, it is used within the scripts that generate the html manual for PLUMED. If you need to use this
49 : tool outside those scripts the input is specified using the following command line arguments.
50 :
51 : \par Examples
52 :
53 : The following generates an example based on the contents of the plumed file plumed.dat
54 : \verbatim
55 : plumed gen_example --plumed plumed.dat --status working
56 : \endverbatim
57 :
58 :
59 : */
60 : //+ENDPLUMEDOC
61 :
62 : class GenExample:
63 : public CLTool {
64 : private:
65 : int multi;
66 : std::string status, version;
67 : Communicator intracomm;
68 : Communicator intercomm;
69 : public:
70 : static void registerKeywords( Keywords& keys );
71 : explicit GenExample(const CLToolOptions& co );
72 : int main(FILE* in, FILE*out,Communicator& pc) override;
73 4 : std::string description()const override {
74 4 : return "construct an example for the manual that users can interact with";
75 : }
76 : void printExampleInput( const std::vector<std::vector<std::string> >& input, const std::string& egname, const std::string& divname, std::ofstream& ofile );
77 : std::vector<std::vector<std::string> > createLongInput( const std::vector<std::vector<std::string> >& input );
78 : };
79 :
80 16330 : PLUMED_REGISTER_CLTOOL(GenExample,"gen_example")
81 :
82 5442 : void GenExample::registerKeywords( Keywords& keys ) {
83 5442 : CLTool::registerKeywords( keys );
84 10884 : keys.add("compulsory","--plumed","plumed.dat","convert the input in this file to the html manual");
85 10884 : keys.add("compulsory","--out","example.html","the file on which to output the example in html");
86 10884 : keys.add("compulsory","--name","ppp","the name to use for this particular input");
87 10884 : keys.add("compulsory","--status","nobadge","whether or not the input file works");
88 10884 : keys.add("compulsory","--multi","0","set number of replicas for multi environment (needs MPI)");
89 5442 : }
90 :
91 4 : GenExample::GenExample(const CLToolOptions& co ):
92 : CLTool(co),
93 4 : multi(0),
94 8 : status("nobadge"),
95 4 : version("master") {
96 4 : inputdata=commandline;
97 4 : }
98 :
99 0 : int GenExample::main(FILE* in, FILE*out,Communicator& pc) {
100 :
101 : // set up for multi replica driver:
102 0 : parse("--multi",multi);
103 0 : if(multi) {
104 0 : int ntot=pc.Get_size();
105 0 : int nintra=ntot/multi;
106 0 : if(multi*nintra!=ntot) {
107 0 : error("invalid number of processes for multi environment");
108 : }
109 0 : pc.Split(pc.Get_rank()/nintra,pc.Get_rank(),intracomm);
110 0 : pc.Split(pc.Get_rank()%nintra,pc.Get_rank(),intercomm);
111 : } else {
112 0 : intracomm.Set_comm(pc.Get_comm());
113 : }
114 :
115 0 : if( config::getVersionLong().find("dev")==std::string::npos ) {
116 0 : version="v"+config::getVersion();
117 : }
118 : std::string fname, egname, outfile;
119 0 : parse("--plumed",fname);
120 0 : parse("--name",egname);
121 0 : parse("--out",outfile);
122 0 : parse("--status",status);
123 :
124 0 : int r=0;
125 0 : if(intracomm.Get_rank()==0) {
126 0 : r=intercomm.Get_rank();
127 : }
128 0 : intracomm.Bcast(r,0);
129 0 : if(r>0) {
130 : outfile="/dev/null";
131 : }
132 :
133 0 : IFile ifile;
134 0 : ifile.open(fname);
135 0 : ifile.allowNoEOL();
136 0 : std::ofstream ofile;
137 0 : ofile.open(outfile);
138 : std::vector<bool> shortcuts;
139 : bool hasshortcuts=false, endplumed=false;
140 : std::vector<std::vector<std::string> > input;
141 : std::vector<std::string> words;
142 0 : while( Tools::getParsedLine(ifile, words, false) ) {
143 0 : input.push_back( words );
144 0 : shortcuts.push_back( false );
145 0 : if( words.empty() || words[0].find("#")!=std::string::npos || endplumed ) {
146 0 : continue;
147 : }
148 0 : std::vector<std::string> interpreted( words );
149 0 : Tools::interpretLabel(interpreted);
150 0 : if( interpreted[0]=="ENDPLUMED" ) {
151 : endplumed=true;
152 : continue;
153 : }
154 0 : Keywords keys;
155 0 : actionRegister().getKeywords( interpreted[0], keys );
156 0 : if( status=="working" && keys.exists("IS_SHORTCUT") ) {
157 0 : hasshortcuts=shortcuts[shortcuts.size()-1]=true;
158 : }
159 0 : }
160 0 : ifile.close();
161 0 : if( hasshortcuts ) {
162 0 : ofile<<"<div style=\"width: 80%; float:left\" id=\"value_details_"<<egname<<"\"> Click on the labels of the actions for more information on what each action computes </div>\n";
163 0 : ofile<<"<div style=\"width: 10%; float:left\"><button type=\"button\" id=\""<<egname<<"_button\" onclick=\'swapInput(\""<<egname<<"\")\'>contract shortcuts</button></div>";
164 : } else {
165 0 : ofile<<"<div style=\"width: 90%; float:left\" id=\"value_details_"<<egname<<"\"> Click on the labels of the actions for more information on what each action computes </div>\n";
166 : }
167 0 : ofile<<"<div style=\"width: 10%; float:left\">";
168 0 : ofile<<"<img src=\"https://img.shields.io/badge/";
169 0 : if(status=="working") {
170 0 : ofile<<version<<"-passing-green";
171 0 : } else if(status=="broken") {
172 0 : ofile<<version<<"-failed-red";
173 0 : } else if(status=="loads") {
174 0 : ofile<<"with-LOAD-yellow";
175 0 : } else if(status=="incomplete") {
176 0 : ofile<<version<<"-incomplete-yellow";
177 0 : } else if ( status=="nobadge" ) {
178 0 : ofile<<"nobadge-36454F";
179 : } else {
180 0 : error("unknown status: "+status);
181 : }
182 0 : ofile<<".svg\" alt=\"tested on "<<version<<"\" /></div>";
183 0 : ofile.flush();
184 0 : if( hasshortcuts ) {
185 : // Write out the short version of the input
186 0 : ofile<<"<div style=\"width: 100%; float:left\" id=\"input_"<<egname<<"\"></div>"<<std::endl;
187 : // Write an extra pre to make sure the html after the example is put in the right place on the page
188 0 : ofile<<"<pre style=\"width: 97%;\" class=\"fragment\"></pre>"<<std::endl;
189 0 : ofile<<"<script type=\"text/javascript\">"<<std::endl;
190 0 : ofile<<"if (window.addEventListener) { // Mozilla, Netscape, Firefox"<<std::endl;
191 0 : ofile<<" window.addEventListener('load', "<<egname<<"Load, false);"<<std::endl;
192 0 : ofile<<"} else if (window.attachEvent) { // IE"<<std::endl;
193 0 : ofile<<" window.attachEvent('onload', "<<egname<<"Load);"<<std::endl;
194 0 : ofile<<"}"<<std::endl;
195 0 : ofile<<"function "<<egname<<"Load(event) {"<<std::endl;
196 0 : ofile<<" swapInput(\""<<egname<<"\");"<<std::endl;
197 0 : ofile<<"}"<<std::endl;
198 0 : ofile<<"</script>"<<std::endl;
199 0 : ofile<<"<div style=\"display:none;\" id=\""<<egname<<"short\">"<<std::endl;
200 0 : printExampleInput( input, egname + "short", egname, ofile );
201 0 : ofile<<"</div>"<<std::endl;
202 : // Write out long version of the input
203 0 : ofile<<"<div style=\"display:none;\" id=\""<<egname<<"long\">";
204 0 : std::vector<std::vector<std::string> > long_input = createLongInput( input );
205 0 : printExampleInput( long_input, egname + "long", egname, ofile );
206 0 : ofile<<"</div>"<<std::endl;
207 0 : } else {
208 0 : printExampleInput( input, egname, egname, ofile );
209 : }
210 0 : ofile.close();
211 0 : return 0;
212 0 : }
213 :
214 0 : std::vector<std::vector<std::string> > GenExample::createLongInput( const std::vector<std::vector<std::string> >& input ) {
215 : std::vector<std::vector<std::string> > long_input;
216 0 : PlumedMain myplumed;
217 0 : int rr=sizeof(double), natoms=10000000;
218 0 : double kt=2.49;
219 0 : myplumed.cmd("setRealPrecision",&rr);
220 0 : if(Communicator::initialized()) {
221 0 : if(multi) {
222 0 : if(intracomm.Get_rank()==0) {
223 0 : myplumed.cmd("GREX setMPIIntercomm",&intercomm.Get_comm());
224 : }
225 0 : myplumed.cmd("GREX setMPIIntracomm",&intracomm.Get_comm());
226 0 : myplumed.cmd("GREX init");
227 : }
228 0 : myplumed.cmd("setMPIComm",&intracomm.Get_comm());
229 : }
230 : bool endplumed=false;
231 0 : myplumed.cmd("setNatoms",&natoms);
232 0 : myplumed.cmd("setKbT",&kt);
233 0 : myplumed.cmd("init");
234 0 : for(unsigned ll=0; ll<input.size(); ++ll) {
235 0 : if( input[ll].empty() || endplumed ) {
236 0 : long_input.push_back( input[ll] );
237 0 : continue;
238 : }
239 0 : if( input[ll][0].find("#")!=std::string::npos ) {
240 0 : long_input.push_back( input[ll] );
241 0 : continue;
242 : }
243 0 : std::vector<std::string> interpreted( input[ll] );
244 0 : Tools::interpretLabel(interpreted);
245 0 : if( interpreted[0]=="ENDPLUMED" ) {
246 : endplumed=true;
247 0 : long_input.push_back( input[ll] );
248 : continue;
249 : }
250 0 : Keywords keys;
251 0 : plumed_assert( actionRegister().check( interpreted[0] ) );
252 0 : actionRegister().getKeywords( interpreted[0], keys );
253 : std::string lab, myinputline;
254 0 : if( Tools::parse(interpreted, "LABEL", lab ) ) {
255 0 : myinputline = lab + ": ";
256 : }
257 0 : myinputline += interpreted[0] + " ";
258 : bool trailingcomment=false;
259 0 : for(unsigned i=1; i<interpreted.size(); ++i) {
260 0 : if( trailingcomment && interpreted[i]=="@newline") {
261 : trailingcomment=false;
262 0 : continue;
263 : }
264 0 : if( interpreted[i].find("#")!=std::string::npos ) {
265 : trailingcomment=true;
266 0 : continue;
267 : }
268 0 : if( interpreted[i]=="@newline" || interpreted[i]=="..." ) {
269 0 : continue;
270 : }
271 : std::size_t pos = 0;
272 0 : while ((pos = interpreted[i].find("@newline",pos)) != std::string::npos) {
273 0 : interpreted[i].replace(pos, 8, "\n");
274 0 : pos++;
275 : }
276 0 : myinputline += interpreted[i] + " ";
277 : }
278 0 : if( status=="working" && keys.exists("IS_SHORTCUT") ) {
279 0 : myplumed.readInputLine( myinputline );
280 0 : ActionShortcut* as=dynamic_cast<ActionShortcut*>( myplumed.getActionSet()[myplumed.getActionSet().size()-1].get() );
281 0 : plumed_assert( as );
282 0 : std::vector<std::string> shortcut_commands = as->getSavedInputLines();
283 0 : for(unsigned i=0; i<shortcut_commands.size(); ++i) {
284 0 : std::vector<std::string> words = Tools::getWords( shortcut_commands[i] );
285 0 : long_input.push_back( words );
286 0 : }
287 0 : } else {
288 0 : long_input.push_back( input[ll] );
289 0 : myplumed.readInputLine( myinputline );
290 : }
291 0 : }
292 0 : return long_input;
293 0 : }
294 :
295 0 : void GenExample::printExampleInput( const std::vector<std::vector<std::string> >& input, const std::string& egname, const std::string& divname, std::ofstream& ofile ) {
296 0 : PlumedMain myplumed;
297 0 : int rr=sizeof(double), natoms=10000000;
298 0 : double kt=2.49;
299 0 : myplumed.cmd("setRealPrecision",&rr);
300 0 : if(Communicator::initialized()) {
301 0 : if(multi) {
302 0 : if(intracomm.Get_rank()==0) {
303 0 : myplumed.cmd("GREX setMPIIntercomm",&intercomm.Get_comm());
304 : }
305 0 : myplumed.cmd("GREX setMPIIntracomm",&intracomm.Get_comm());
306 0 : myplumed.cmd("GREX init");
307 : }
308 0 : myplumed.cmd("setMPIComm",&intracomm.Get_comm());
309 : }
310 0 : myplumed.cmd("setNatoms",&natoms);
311 0 : myplumed.cmd("setKbT",&kt);
312 0 : myplumed.cmd("init");
313 : std::vector<std::string> labellist;
314 : bool endplumed=false;
315 0 : ofile<<"<pre style=\"width: 97%;\" class=\"fragment\">"<<std::endl;
316 0 : for(unsigned ll=0; ll<input.size(); ++ll) {
317 0 : if( input[ll].empty() ) {
318 : ofile<<std::endl;
319 0 : continue;
320 : }
321 0 : if( input[ll][0].find("#")!=std::string::npos || endplumed ) {
322 0 : ofile<<"<span style=\"color:blue\">"<<input[ll][0];
323 0 : for(unsigned i=1; i<input[ll].size(); ++i) {
324 0 : ofile<<" "<<input[ll][i];
325 : }
326 0 : ofile<<"</span>"<<std::endl;;
327 : } else {
328 : // Interpret the label if this needs to be done
329 0 : std::vector<std::string> interpreted( input[ll] );
330 0 : Tools::interpretLabel(interpreted);
331 : std::string lab, myinputline;
332 : // Now read in the label
333 0 : if( Tools::parse(interpreted,"LABEL",lab) ) {
334 0 : ofile<<"<b name=\""<<egname<<lab<<"\" onclick=\'showPath(\""<<divname<<"\",\""<<egname<<lab<<"\")\'>"<<lab<<": </b>";
335 0 : labellist.push_back(lab);
336 0 : myinputline = lab + ": ";
337 : }
338 : // Print the keyword in use in the action
339 0 : std::string action = interpreted[0];
340 0 : myinputline += interpreted[0] + " ";
341 0 : if( action=="ENDPLUMED" ) {
342 : endplumed=true;
343 : }
344 0 : Keywords keys;
345 0 : actionRegister().getKeywords( interpreted[0], keys );
346 : // Handle conversion of action names to links
347 0 : std::transform(action.begin(), action.end(), action.begin(), [](unsigned char c) {
348 0 : return std::tolower(c);
349 : });
350 0 : ofile<<"<a href=\"https://www.plumed.org/doc-"<<version<<"/user-doc/html/";
351 : for(unsigned n=0;; ++n) {
352 0 : std::size_t und=action.find_first_of("_");
353 0 : if( und==std::string::npos ) {
354 : break;
355 : }
356 0 : std::string first=action.substr(0,und);
357 0 : for(auto c : first ) {
358 0 : if( isdigit(c) ) {
359 0 : ofile<<c;
360 : } else {
361 0 : ofile<<"_"<<c;
362 : }
363 : }
364 0 : ofile<<"_";
365 0 : action=action.substr(und+1);
366 0 : }
367 0 : for(auto c : action ) {
368 0 : if( isdigit(c) ) {
369 0 : ofile<<c;
370 : } else {
371 0 : ofile<<"_"<<c;
372 : }
373 : }
374 0 : ofile<<".html\" style=\"color:green\">"<<interpreted[0]<<"</a> ";
375 : // And write out everything else in the input line
376 : bool trailingcomment=false;
377 0 : for(unsigned i=1; i<interpreted.size(); ++i) {
378 0 : if( interpreted[i]=="@newline" && i==1 ) {
379 0 : ofile<<"..."<<std::endl<<" ";
380 0 : continue;
381 0 : } else if( interpreted[i]=="@newline" ) {
382 0 : if( trailingcomment ) {
383 0 : ofile<<"</span>";
384 : trailingcomment=false;
385 : }
386 0 : if( interpreted[i+1]=="..." ) {
387 : ofile<<std::endl;
388 : } else {
389 0 : ofile<<std::endl<<" ";
390 : }
391 0 : continue;
392 0 : } else if( interpreted[i]=="__FILL__" ) {
393 0 : if( status!="incomplete" ) {
394 0 : error("found __FILL__ statement but status is " + status);
395 : }
396 0 : ofile<<"<span style=\"background-color:yellow\">__FILL__</span>";
397 0 : continue;
398 0 : } else if( interpreted[i]==action ) {
399 0 : continue;
400 : }
401 0 : if( interpreted[i].find("#")!=std::string::npos ) {
402 : trailingcomment=true;
403 0 : ofile<<"<span style=\"color:blue\">";
404 : }
405 :
406 0 : if( !trailingcomment ) {
407 0 : std::size_t eq=interpreted[i].find_first_of("=");
408 0 : if( eq!=std::string::npos ) {
409 0 : std::string keyword=interpreted[i].substr(0,eq), rest=interpreted[i].substr(eq+1);
410 0 : ofile<<"<span class=\"tooltip\">"<<keyword<<"<span class=\"right\">"<<keys.getTooltip(keyword)<<"<i></i></span></span>";
411 0 : if( rest=="__FILL__" ) {
412 0 : if( status!="incomplete" ) {
413 0 : error("found __FILL__ statement but status is " + status);
414 : }
415 0 : ofile<<"=<span style=\"background-color:yellow\">__FILL__</span>";
416 0 : } else if( rest.find_first_of("{")!=std::string::npos ) {
417 : std::size_t pos = 0;
418 0 : while ((pos = rest.find("@newline",pos)) != std::string::npos) {
419 0 : rest.replace(pos, 8, "\n");
420 0 : pos++;
421 : }
422 0 : ofile<<"="<<rest<<" ";
423 0 : myinputline += keyword + "=" + rest + " ";
424 : } else {
425 0 : std::vector<std::string> args=Tools::getWords(rest,"\t\n ,");
426 0 : ofile<<"=";
427 0 : for(unsigned i=0; i<args.size(); ++i) {
428 : bool islabel=false;
429 : std::string thislab;
430 0 : for(unsigned j=0; j<labellist.size(); ++j) {
431 0 : std::size_t dot=args[i].find_first_of(".");
432 0 : std::string lll=args[i].substr(0,dot);
433 0 : if( lll==labellist[j] ) {
434 : islabel=true;
435 : thislab=labellist[j];
436 : break;
437 : }
438 : }
439 : if( islabel ) {
440 0 : ofile<<"<b name=\""<<egname<<thislab<<"\">"<<args[i]<<"</b>";
441 : } else {
442 : ofile<<args[i];
443 : }
444 0 : if( i!=args.size()-1 ) {
445 0 : ofile<<",";
446 : }
447 : }
448 0 : myinputline += interpreted[i] + " ";
449 0 : }
450 0 : ofile<<" ";
451 0 : } else if( interpreted[i]!="@newline" && interpreted[i]!="..." ) {
452 0 : myinputline += interpreted[i] + " ";
453 0 : ofile<<"<span class=\"tooltip\">"<<interpreted[i]<<"<span class=\"right\">"<<keys.getTooltip(interpreted[i])<<"<i></i></span></span> ";
454 0 : } else if( interpreted[i]=="..." ) {
455 0 : ofile<<"...";
456 : }
457 : } else {
458 0 : ofile<<interpreted[i]<<" ";
459 : }
460 : }
461 0 : if( trailingcomment ) {
462 0 : ofile<<"</span>";
463 : }
464 : // This builds the hidden content that tells the user about what is calculated
465 0 : if( status=="working" ) {
466 0 : ofile<<"<span style=\"display:none;\" id=\""<<egname<<lab<<"\">";
467 0 : ofile<<"The "<<interpreted[0]<<" action with label <b>"<<lab<<"</b>";
468 0 : myplumed.readInputLine( myinputline );
469 0 : ActionWithValue* av=myplumed.getActionSet().selectWithLabel<ActionWithValue*>(lab);
470 0 : if( av ) {
471 0 : if( av->getNumberOfComponents()==1 ) {
472 0 : ofile<<" calculates a single scalar value";
473 0 : } else if( av->getNumberOfComponents()>0 ) {
474 0 : ofile<<" calculates the following quantities:"<<std::endl;
475 0 : ofile<<"<table align=\"center\" frame=\"void\" width=\"95%%\" cellpadding=\"5%%\">"<<std::endl;
476 0 : ofile<<"<tr><td width=\"5%%\"><b> Quantity </b> </td><td><b> Description </b> </td></tr>"<<std::endl;
477 0 : unsigned ncomp = av->getNumberOfComponents();
478 0 : for(unsigned k=0; k<ncomp; ++k ) {
479 0 : std::string myname = av->copyOutput(k)->getName();
480 0 : std::size_t dot=myname.find_first_of(".");
481 0 : std::string tname=myname.substr(dot+1);
482 0 : ofile<<"<tr><td width=\"5%%\">"<<myname<<"</td><td>"<<av->getOutputComponentDescription(tname,keys)<<"</td></tr>"<<std::endl;
483 : }
484 0 : ofile<<"</table>"<<std::endl;
485 : }
486 : } else {
487 0 : ActionWithVirtualAtom* avv=myplumed.getActionSet().selectWithLabel<ActionWithVirtualAtom*>(lab);
488 0 : if( avv ) {
489 0 : ofile<<" calculates the position of a virtual atom";
490 0 : } else if( interpreted[0]=="GROUP" ) {
491 0 : ofile<<" defines a group of atoms so that they can be referred to later in the input";
492 : }
493 : }
494 0 : ofile<<"</span>"<<std::endl;
495 : } else {
496 0 : ofile<<"<span style=\"display:none;\" id=\""<<egname<<lab<<"\"> You cannot view the components that are calculated by each action for this input file. Sorry </span>"<<std::endl;
497 : }
498 0 : }
499 0 : ofile.flush();
500 : }
501 0 : ofile<<"</pre>"<<std::endl;
502 0 : }
503 :
504 : } // End of namespace
505 : }
|
