Added documentation for output components in shortcuts

regtest/dimred/rt-smap-osample/plumed.dat

@@ -19,5 +19,5 @@ smap: SKETCHMAP ...
   LOW_DIM_FUNCTION={SMAP R_0=4 A=1 B=2} CGTOL=1E-4 OS_CGTOL=1E-3
 ...
 
-DUMPVECTOR ARG=smap.*,lwe FMT=%8.4f FILE=smap
-DUMPVECTOR ARG=smap_osample.coord-1,smap_osample.coord-2,weights FILE=projections FMT=%8.2f
+DUMPVECTOR ARG=smap,lwe FMT=%8.4f FILE=smap
+DUMPVECTOR ARG=smap_osample,weights FILE=projections FMT=%8.2f

regtest/dimred/rt-smap-osample/projections.reference

@@ -1,4 +1,4 @@
-#! FIELDS time parameter smap_osample.coord-1 smap_osample.coord-2 weights
+#! FIELDS time parameter smap_osample_pp.coord-1 smap_osample_pp.coord-2 weights
  500.000000 0     0.75     1.97     1.00
  500.000000 1    -0.41    -2.02     1.00
  500.000000 2    -1.23     0.97     1.00

regtest/dimred/rt-smap-osample/smap.reference

@@ -1,4 +1,4 @@
-#! FIELDS time parameter smap.coord-1 smap.coord-2 lwe
+#! FIELDS time parameter smap_ap.coord-1 smap_ap.coord-2 lwe
  500.000000 0   0.7566   1.9772   2.0000
  500.000000 1  -1.2291   0.9669   1.0000
  500.000000 2   0.6420  -0.6544   4.0000

regtest/dimred/rt-smap-pointwise/smap.reference

@@ -1,4 +1,4 @@
-#! FIELDS time parameter smap.coord-1 smap.coord-2 lwe
+#! FIELDS time parameter smap_ap.coord-1 smap_ap.coord-2 lwe
  100.000000 0    3.069   -0.094    1.000
  100.000000 1    2.470   -3.680    1.000
  100.000000 2    4.827    0.498    1.000

regtest/dimred/rt-smap-smacof/smap.reference

@@ -1,4 +1,4 @@
-#! FIELDS time parameter smap.coord-1 smap.coord-2 lwe
+#! FIELDS time parameter smap_ap.coord-1 smap_ap.coord-2 lwe
  500.000000 0   -966.3   1318.3      1.0
  500.000000 1   -607.3    827.1      1.0
  500.000000 2     26.7    -36.8      1.0

regtest/dimred/rt-smap1/smap.reference

@@ -1,4 +1,4 @@
-#! FIELDS time parameter smap.coord-1 smap.coord-2 weights
+#! FIELDS time parameter smap_ap.coord-1 smap_ap.coord-2 weights
  50.000000 0  18.8066  10.1521   1.0000
  50.000000 1  14.0852   9.9268   1.0000
  50.000000 2   8.3328   9.6157   1.0000

src/adjmat/Bridge.cpp

@@ -55,6 +55,7 @@ void Bridge::registerKeywords(Keywords& keys) {
   keys.add("optional","SWITCHB","The switchingfunction on the distance between the bridging atoms and the atoms in "
            "group B");
   keys.needsAction("BRIDGE_MATRIX"); keys.needsAction("SUM");
+  keys.setValueDescription("the number of bridging atoms between the two groups");
 }
 
 Bridge::Bridge(const ActionOptions& ao):

src/adjmat/ContactMatrixShortcut.cpp

@@ -24,6 +24,7 @@
 #include "core/PlumedMain.h"
 #include "core/ActionSet.h"
 #include "core/Group.h"
+#include "AdjacencyMatrixBase.h"
 
 //+PLUMEDOC MATRIX CONTACT_MATRIX
 /*
@@ -69,20 +70,13 @@ class ContactMatrixShortcut : public ActionShortcut {
 PLUMED_REGISTER_ACTION(ContactMatrixShortcut,"CONTACT_MATRIX")
 
 void ContactMatrixShortcut::registerKeywords(Keywords& keys) {
-  ActionShortcut::registerKeywords( keys );
-  keys.add("atoms","GROUPA","");
-  keys.add("atoms","GROUPB","");
-  keys.add("atoms-2","ATOMS","the atoms for which you would like to calculate the adjacency matrix (basically equivalent to GROUP)");
-  keys.add("numbered","GROUP","specifies the list of atoms that should be assumed indistinguishable");
+  AdjacencyMatrixBase::registerKeywords( keys );
+  keys.remove("GROUP"); keys.add("numbered","GROUP","specifies the list of atoms that should be assumed indistinguishable");
   keys.add("compulsory","NN","6","The n parameter of the switching function ");
   keys.add("compulsory","MM","0","The m parameter of the switching function; 0 implies 2*NN");
   keys.add("compulsory","D_0","0.0","The d_0 parameter of the switching function");
   keys.add("compulsory","R_0","The r_0 parameter of the switching function");
   keys.add("numbered","SWITCH","specify the switching function to use between two sets of indistinguishable atoms");
-  keys.add("compulsory","NL_CUTOFF","0.0","The cutoff for the neighbor list.  A value of 0 means we are not using a neighbor list");
-  keys.add("compulsory","NL_STRIDE","1","The frequency with which we are updating the atoms in the neighbor list");
-  keys.addFlag("COMPONENTS",false,"also calculate the components of the vector connecting the atoms in the contact matrix");
-  keys.addFlag("NOPBC",false,"don't use pbc");
   keys.addActionNameSuffix("_PROPER"); keys.needsAction("TRANSPOSE"); keys.needsAction("CONCATENATE");
 }
 

src/cltools/Driver.cpp

@@ -776,8 +776,9 @@ int Driver<real>::main(FILE* in,FILE*out,Communicator& pc) {
       if( valuedict_file.length()>0 ) {
         OFile valuefile; valuefile.open( valuedict_file ); valuefile.printf("{\n"); bool firsta=true;
         for(const auto & pp : p.getActionSet()) {
+          if( pp.get()->getName()=="CENTER" ) continue ;
           ActionWithVirtualAtom* avv=dynamic_cast<ActionWithVirtualAtom*>(pp.get());
-          if( avv ||  pp.get()->getName()=="GROUP" ) {
+          if( avv ||  pp.get()->getName()=="GROUP" || pp.get()->getName()=="DENSITY" ) {
             Action* p(pp.get());
             if( firsta ) { valuefile.printf("  \"%s\" : {\n", p->getLabel().c_str() ); firsta=false; }
             else valuefile.printf(",\n  \"%s\" : {\n", p->getLabel().c_str() );
@@ -791,22 +792,46 @@ int Driver<real>::main(FILE* in,FILE*out,Communicator& pc) {
             else valuefile.printf(",\n  \"%s\" : {\n", av->getLabel().c_str() );
             bool firstv=true; Keywords keys; actionRegister().getKeywords( av->getName(), keys );
             for(unsigned i=0; i<av->getNumberOfComponents(); ++i) {
-              Value* myval = av->copyOutput(i); std::string compname = myval->getName(), vtype, description;  std::size_t dot=compname.find(".");
-              if( myval->getRank()==0 ) vtype="scalar";
-              else if( myval->getRank()>0 && myval->hasDerivatives() ) vtype="grid";
-              else if( myval->getRank()==1 ) vtype="vector";
-              else if( myval->getRank()==2 ) vtype="matrix";
-              else plumed_merror("unknown type for value " + myval->getName() );
+              Value* myval = av->copyOutput(i); std::string compname = myval->getName(), description; std::size_t dot=compname.find(".");
               if( dot!=std::string::npos ) {
                 std::string cname = compname.substr(dot+1); description = av->getOutputComponentDescription( cname, keys );
               } else description = keys.getOutputComponentDescription(".#!value");
               if( description.find("\\")!=std::string::npos ) error("found invalid backslash character in documentation for component " + compname + " in action " + av->getName() + " with label " + av->getLabel() );
-              if( firstv ) { valuefile.printf("    \"%s\" : { \"type\": \"%s\", \"description\": \"%s\" }", myval->getName().c_str(), vtype.c_str(), description.c_str() ); firstv=false; }
-              else valuefile.printf(",\n    \"%s\" : { \"type\": \"%s\", \"description\": \"%s\" }", myval->getName().c_str(), vtype.c_str(), description.c_str() );
+              if( firstv ) { valuefile.printf("    \"%s\" : { \"type\": \"%s\", \"description\": \"%s\" }", myval->getName().c_str(), myval->getValueType().c_str(), description.c_str() ); firstv=false; }
+              else valuefile.printf(",\n    \"%s\" : { \"type\": \"%s\", \"description\": \"%s\" }", myval->getName().c_str(), myval->getValueType().c_str(), description.c_str() );
             }
             valuefile.printf("\n  }");
           }
           ActionShortcut* as=pp->castToActionShortcut();
+          if( as ) {
+            unsigned ncomponents = 0; std::vector<ActionWithValue*> val_actions;
+            Keywords keys; actionRegister().getKeywords( as->getName(), keys );
+            std::vector<std::string> cnames( keys.getOutputComponents().size() );
+            for(unsigned i=0; i<cnames.size(); ++i) {
+              std::string valname;
+              if( cnames[i]==".#!value" ) valname = as->getShortcutLabel();
+              else valname = as->getShortcutLabel() + "_" + cnames[i];
+              ActionWithValue* av = p.getActionSet().selectWithLabel<ActionWithValue*>( valname );
+              if( av ) val_actions.push_back(av);
+            }
+            if( val_actions.size()==0 ) continue ;
+
+            if( firsta ) { valuefile.printf("  \"shortcut_%s\" : {\n", as->getShortcutLabel().c_str() ); firsta=false; }
+            else valuefile.printf(",\n  \"shortcut_%s\" : {\n", as->getShortcutLabel().c_str() );
+            bool firstv=true;
+            for(unsigned i=0; i<val_actions.size(); ++i) {
+              for(unsigned j=0; j<val_actions[i]->getNumberOfComponents(); ++j) {
+                Value* myval = val_actions[i]->copyOutput(j); std::string compname = myval->getName(), description; std::size_t dot=compname.find(".");
+                if( dot!=std::string::npos ) {
+                  std::string cname = compname.substr(dot+1); description = val_actions[i]->getOutputComponentDescription( cname, keys );
+                } else description = description = keys.getOutputComponentDescription(".#!value");
+                if( description.find("\\")!=std::string::npos ) error("found invalid backslash character in documentation for component " + compname + " in action " + val_actions[i]->getName() + " with label " + val_actions[i]->getLabel() );
+                if( firstv ) { valuefile.printf("    \"%s\" : { \"type\": \"%s\", \"description\": \"%s\" }", myval->getName().c_str(), myval->getValueType().c_str(), description.c_str() ); firstv=false; }
+                else valuefile.printf(",\n    \"%s\" : { \"type\": \"%s\", \"description\": \"%s\" }", myval->getName().c_str(), myval->getValueType().c_str(), description.c_str() );
+              }
+            }
+            valuefile.printf("\n  }");
+          }
         }
         valuefile.printf("\n}\n"); valuefile.close();
       }

src/cltools/GenJson.cpp

@@ -141,12 +141,7 @@ int GenJson::main(FILE* in, FILE*out,Communicator& pc) {
         std::cout<<"           \"description\": \""<<mydescrip<<"\""<<std::endl;
         if( k==components.size()-1 ) std::cout<<"         }"<<std::endl; else std::cout<<"         },"<<std::endl;
       }
-      if( hasvalue ) {
-        std::cout<<"         \"value\" : {"<<std::endl;
-        std::cout<<"           \"flag\": \"default\","<<std::endl;
-        std::cout<<"           \"description\": \"something calculated by "<<action_names[i]<<"\""<<std::endl;
-        std::cout<<"         }"<<std::endl;
-      }
+      if( hasvalue && components.size()==0 ) plumed_merror("no components have been registered for action " + action_names[i] );
       std::cout<<"       }"<<std::endl;
 
     }

src/clusters/ClusterDiameter.cpp

@@ -72,6 +72,7 @@ void ClusterDiameter::registerKeywords( Keywords& keys ) {
   ActionShortcut::registerKeywords( keys );
   keys.add("optional","ARG","calculate ths radius of the cluster that are in this particular cluster");
   keys.add("compulsory","ATOMS","the atoms that were used to calculate the matrix that was clustered");
+  keys.setValueDescription("the largest of all the distances between the pairs of atom in the cluster");
   keys.needsAction("DISTANCE_MATRIX"); keys.needsAction("OUTER_PRODUCT"); keys.needsAction("CUSTOM");
   keys.needsAction("FLATTEN"); keys.needsAction("HIGHEST");
 }

src/clusters/ClusterNatoms.cpp

@@ -46,6 +46,7 @@ void ClusterNatoms::registerKeywords(Keywords& keys) {
   ActionShortcut::registerKeywords( keys );
   keys.add("compulsory","CLUSTERS","the label of the action that does the clustering");
   keys.add("compulsory","CLUSTER","1","which cluster would you like to look at 1 is the largest cluster, 2 is the second largest, 3 is the the third largest and so on.");
+  keys.setValueDescription("the number of atoms in the cluster");
   keys.needsAction("CLUSTER_WEIGHTS"); keys.needsAction("SUM");
 }
 

src/clusters/ClusterWithSurface.cpp

@@ -49,6 +49,7 @@ void ClusterWithSurface::registerKeywords(Keywords& keys) {
   keys.add("compulsory","ATOMS","the atoms that were used to calculate the matrix that was clustered");
   keys.add("compulsory","CLUSTERS","the label of the action that does the clustering");
   keys.add("compulsory","CLUSTER","1","which cluster would you like to look at 1 is the largest cluster, 2 is the second largest, 3 is the the third largest and so on.");
+  keys.setValueDescription("a vector that is one for those atoms that are within the cluster or that are within a cetain cutoff of one of the atoms in the cluster and zero otherwise");
   keys.needsAction("CLUSTER_WEIGHTS"); keys.needsAction("CONTACT_MATRIX");
   keys.needsAction("OUTER_PRODUCT"); keys.needsAction("CUSTOM");
   keys.needsAction("DFSCLUSTERING");

src/clusters/OutputCluster.cpp

@@ -72,7 +72,7 @@ void OutputCluster::registerKeywords( Keywords& keys ) {
   keys.add("compulsory","CLUSTER","1","which cluster would you like to look at 1 is the largest cluster, 2 is the second largest, 3 is the the third largest and so on");
   keys.add("compulsory","STRIDE","1","the frequency with which you would like to output the atoms in the cluster");
   keys.add("compulsory","FILE","the name of the file on which to output the details of the cluster");
-  keys.needsAction("PRINT_NDX");
+  keys.remove("HAS_VALUES"); keys.needsAction("PRINT_NDX");
 }
 
 OutputCluster::OutputCluster(const ActionOptions& ao):

src/colvar/DRMSD.cpp

@@ -125,6 +125,7 @@ void DRMSD::registerKeywords( Keywords& keys ) {
   keys.addFlag("NOPBC",false,"ignore the periodic boundary conditions when calculating distances");
   // This is just ignored in reality which is probably bad
   keys.addFlag("NUMERICAL_DERIVATIVES",false,"calculate the derivatives for these quantities numerically");
+  keys.setValueDescription("the DRMSD distance between the instantaneous structure and the reference structure");
   keys.needsAction("SUM"); keys.needsAction("DISTANCE"); keys.needsAction("CONSTANT"); keys.needsAction("EUCLIDEAN_DISTANCE"); keys.needsAction("CUSTOM");
 }
 

src/colvar/ExtraCV.cpp

@@ -69,6 +69,7 @@ ExtraCV::ExtraCV(const ActionOptions&ao):
 void ExtraCV::registerKeywords( Keywords& keys ) {
   ActionShortcut::registerKeywords( keys );
   keys.add("compulsory","NAME","name of the CV as computed by the MD engine");
+  keys.setValueDescription("the value of the CV that was passed from the MD code to PLUMED");
   keys.needsAction("PUT"); keys.needsAction("COMBINE");
 }
 

src/colvar/GyrationShortcut.cpp

@@ -66,6 +66,7 @@ void GyrationShortcut::registerKeywords( Keywords& keys ) {
   keys.addFlag("MASS",false,"calculate the center of mass");
   keys.addFlag("MASS_WEIGHTED",false,"set the masses of all the atoms equal to one");
   keys.addFlag("UNORMALIZED",false,"do not divide by the sum of the weights");
+  keys.setValueDescription("the radius that was computed from the weights");
   keys.addActionNameSuffix("_FAST"); keys.needsAction("CENTER"); keys.needsAction("CONSTANT");
   keys.needsAction("ONES"); keys.needsAction("MASS"); keys.needsAction("DISTANCE");
   keys.needsAction("COVARIANCE_MATRIX"); keys.needsAction("SELECT_COMPONENTS");

src/colvar/MultiRMSD.cpp

@@ -58,6 +58,7 @@ void MultiRMSD::registerKeywords(Keywords& keys) {
   keys.add("compulsory","TYPE","SIMPLE","the manner in which RMSD alignment is performed.  Should be MULTI-OPTIMAL, MULTI-OPTIMAL-FAST,  MULTI-SIMPLE or MULTI-DRMSD.");
   keys.addFlag("SQUARED",false," This should be set if you want the mean squared displacement instead of the root mean squared displacement");
   keys.addFlag("NOPBC",false,"don't use periodic boundary conditions");
+  keys.setValueDescription("the sum of the multiple RMSD distances");
   keys.needsAction("CONSTANT"); keys.needsAction("WHOLEMOLECULES"); keys.needsAction("POSITION");
   keys.needsAction("CONCATENATE"); keys.needsAction("RMSD_VECTOR"); keys.needsAction("COMBINE"); keys.needsAction("CUSTOM");
 }

src/colvar/RMSDShortcut.cpp

@@ -45,6 +45,7 @@ void RMSDShortcut::registerKeywords(Keywords& keys) {
   keys.addFlag("NUMERICAL_DERIVATIVES", false, "calculate the derivatives for these quantities numerically");
   keys.addFlag("DISPLACEMENT",false,"Calculate the vector of displacements instead of the length of this vector");
   keys.add("compulsory","NUMBER","0","if there are multiple structures in the pdb file you can specify that you want the RMSD from a specific structure by specifying its place in the file here. If NUMBER=0 then the RMSD from all structures are computed");
+  keys.setValueDescription("the RMSD distance between the instaneous structure and the reference structure/s that were input");
   keys.addActionNameSuffix("_SCALAR"); keys.addActionNameSuffix("_VECTOR");
   keys.needsAction("PDB2CONSTANT"); keys.needsAction("WHOLEMOLECULES");
   keys.needsAction("POSITION"); keys.needsAction("CONCATENATE");

src/core/ActionShortcut.cpp

@@ -30,6 +30,7 @@ namespace PLMD {
 void ActionShortcut::registerKeywords( Keywords& keys ) {
   Action::registerKeywords( keys );
   keys.add("hidden","IS_SHORTCUT","hidden keyword to tell if actions are shortcuts so that example generator can provide expansions of shortcuts");
+  keys.add("hidden","HAS_VALUES","this is used in json output to determine those actions that have values");
 }
 
 void ActionShortcut::readShortcutKeywords( const Keywords& keys, std::map<std::string,std::string>& keymap ) {

src/core/ActionWithValue.cpp

@@ -45,6 +45,7 @@ void ActionWithValue::noAnalyticalDerivatives(Keywords& keys) {
 }
 
 void ActionWithValue::useCustomisableComponents(Keywords& keys) {
+  if( !keys.outputComponentExists(".#!custom") ) keys.addOutputComponent(".#!custom","default","the names of the output components for this action depend on the actions input file see the example inputs below for details");
   keys.setComponentsIntroduction("The names of the components in this action can be customized by the user in the "
                                  "actions input file.  However, in addition to the components that can be customized the "
                                  "following quantities will always be output");

src/core/Value.cpp

@@ -381,4 +381,13 @@ bool Value::calculateOnUpdate() const {
   return (valtype==average || valtype==calcFromAverage);
 }
 
+std::string Value::getValueType() const {
+  if( getRank()==0 ) return "scalar";
+  if( getRank()>0 && hasDerivatives() ) return "grid";
+  if( getRank()==1 ) return "vector";
+  if( getRank()==2 ) return "matrix";
+  plumed_merror("unknown type for value " + getName() );
+  return "";
+}
+
 }

src/core/Value.h

@@ -242,6 +242,8 @@ class Value {
   void setGridDerivatives( const unsigned& n, const unsigned& j, const double& val );
 /// Add another value to the end of the data vector held by this value.  This is used in COLLECT
   void push_back( const double& val );
+/// Get the type of value that is stored here
+  std::string getValueType() const ;
 };
 
 inline

src/crystdistrib/BopsShortcut.cpp

@@ -63,6 +63,7 @@ void BopsShortcut::registerKeywords( Keywords& keys ) {
   keys.add("compulsory","KERNELFILE_BOPS","the second file containing the list of kernel parameters. Expecting a normalization factor (height), concentration parameter (kappa), and 3 norm vector pieces of the mean (mu_i, mu_j, mu_k )for a fisher distribution. of the form h*exp(kappa*dot(r_mean,r)), where dot is a standard dot product.");
   keys.add("compulsory", "CUTOFF", "cutoff for the distance matrix");
 //  keys.add("compulsory","SWITCH","the switching function that acts on the distances between points)");
+  keys.setValueDescription("the values of the bops order parameters");
   keys.needsAction("DISTANCE_MATRIX"); keys.needsAction("QUATERNION_BOND_PRODUCT_MATRIX"); keys.needsAction("CUSTOM");
   keys.needsAction("ONES"); keys.needsAction("MATRIX_VECTOR_PRODUCT");
 }

src/crystdistrib/DopsShortcut.cpp

@@ -60,6 +60,7 @@ void DopsShortcut::registerKeywords( Keywords& keys ) {
            "the documentation for that keyword");
   keys.add("compulsory","KERNELFILE","the file containing the list of kernel parameters.  We expect h, mu and sigma parameters for a 1D Gaussian kernel of the form h*exp(-(x-mu)^2/2sigma^2)");
   keys.add("compulsory","CUTOFF","6.25","to make the calculation faster we calculate a cutoff value on the distances.  The input to this keyword determines x in this expreession max(mu + sqrt(2*x)/sigma)");
+  keys.setValueDescription("the values of the DOPS order parameters");
   keys.needsAction("DISTANCE_MATRIX"); keys.needsAction("CUSTOM"); keys.needsAction("ONES"); keys.needsAction("MATRIX_VECTOR_PRODUCT");
 }