GROMACS $VER Online Reference

-http://www.gromacs.org
- - -EOD - -echo "Generating html manual for GROMACS programs" -echo "-------------------------------------------" - -cd $dir - -setenv GMX_MAXBACKUP -1 -foreach program ( $PROGRAMS ) - if ( ( -x $GMXBINDIR/$program ) && ( $program != "my_dssp" ) && ( $program != "GMXRC" ) && ( $program != "completion.csh" ) && ( $program != "completion.zsh" ) && ( $program != "average" ) && ( $program != "completion.bash" ) && ( $program != "demux.pl" ) ) then - echo -n "$program " - cd $HTMLOL - $GMXBINDIR/$program -quiet -man html >& /dev/null - cd .. - endif - endif -end -echo - -#last line diff --git a/share/html/online.html b/share/html/online.html index 1d4b5f0162..143c588bfe 100644 --- a/share/html/online.html +++ b/share/html/online.html @@ -46,6 +46,8 @@ Sat 19 Jan 2013 Options

All Programs Alphabetically +

+Programs by Topic diff --git a/src/gromacs/commandline/cmdlinemodulemanager.cpp b/src/gromacs/commandline/cmdlinemodulemanager.cpp index 3486a1e48c..d4524aa6d8 100644 --- a/src/gromacs/commandline/cmdlinemodulemanager.cpp +++ b/src/gromacs/commandline/cmdlinemodulemanager.cpp @@ -70,15 +70,104 @@ #include "gromacs/utility/init.h" #include "gromacs/utility/programinfo.h" #include "gromacs/utility/stringutil.h" +#include "gromacs/utility/uniqueptr.h" namespace gmx { //! Container type for mapping module names to module objects. typedef std::map CommandLineModuleMap; +//! Smart pointer type for managing a CommandLineModuleGroup. +typedef gmx_unique_ptr::type + CommandLineModuleGroupDataPointer; +//! Container type for keeping a list of module groups. +typedef std::vector + CommandLineModuleGroupList; class CommandLineHelpModule; +namespace internal +{ + +/*! \internal + * \brief + * Internal data for a CommandLineModuleManager module group. + * + * This class contains the state of a module group. CommandLineModuleGroup + * provides the public interface to construct/alter the state, and + * CommandLineModuleManager and its associated classes use it for help output. + * + * \ingroup module_commandline + */ +class CommandLineModuleGroupData +{ + public: + /*! \brief + * Shorthand for a list of modules contained in the group. + * + * The first element in the contained pair contains the tag + * (gmx-something) of the module, and the second element contains the + * description. The second element is never NULL. + */ + typedef std::vector > ModuleList; + + /*! \brief + * Constructs an empty module group. + * + * \param[in] modules List of all modules + * (used for checking and default descriptions). + * \param[in] title Title of the group. + * + * Does not throw. + */ + CommandLineModuleGroupData(const CommandLineModuleMap &modules, + const char *title) + : allModules_(modules), title_(title) + { + } + + //! Returns the title for the group. + const char *title() const { return title_; } + //! Returns the list of modules in the group. + const ModuleList &modules() const { return modules_; } + + /*! \brief + * Adds a module to the group. + * + * \param[in] name Name of the module. + * \param[in] description Description of the module in this group. + * \throws std::bad_alloc if out of memory. + * + * If \p description is NULL, the description returned by the module is + * used. + */ + void addModule(const char *name, const char *description) + { + CommandLineModuleMap::const_iterator moduleIter = allModules_.find(name); + GMX_RELEASE_ASSERT(moduleIter != allModules_.end(), + "Non-existent module added to a group"); + if (description == NULL) + { + description = moduleIter->second->shortDescription(); + GMX_RELEASE_ASSERT(description != NULL, + "Module without a description added to a group"); + } + const char *const program = + ProgramInfo::getInstance().invariantProgramName().c_str(); + std::string tag(formatString("%s-%s", program, name)); + modules_.push_back(std::make_pair(tag, description)); + } + + private: + const CommandLineModuleMap &allModules_; + const char *title_; + ModuleList modules_; + + GMX_DISALLOW_COPY_AND_ASSIGN(CommandLineModuleGroupData); +}; + +} // namespace internal + namespace { @@ -244,6 +333,10 @@ class ModuleHelpTopic : public HelpTopicInterface class HelpExportInterface { public: + //! Shorthand for a list of modules contained in a group. + typedef internal::CommandLineModuleGroupData::ModuleList + ModuleGroupContents; + virtual ~HelpExportInterface() {}; /*! \brief @@ -269,6 +362,28 @@ class HelpExportInterface * etc. */ virtual void finishModuleExport() = 0; + + /*! \brief + * Called once before exporting module groups. + * + * Can, e.g., open a single output file for listing all the groups. + */ + virtual void startModuleGroupExport() = 0; + /*! \brief + * Called to export the help for each module group. + * + * \param[in] title Title for the group. + * \param[in] modules List of modules in the group. + */ + virtual void exportModuleGroup(const char *title, + const ModuleGroupContents &modules) = 0; + /*! \brief + * Called after all module groups have been exported. + * + * Can close files opened in startModuleGroupExport(), write footers to them + * etc. + */ + virtual void finishModuleGroupExport() = 0; }; /******************************************************************** @@ -287,6 +402,14 @@ class HelpExportMan : public HelpExportInterface virtual void exportModuleHelp(const std::string &tag, const CommandLineModuleInterface &module); virtual void finishModuleExport() {} + + virtual void startModuleGroupExport() {} + virtual void exportModuleGroup(const char * /*title*/, + const ModuleGroupContents & /*modules*/) {} + virtual void finishModuleGroupExport() {} + + private: + boost::scoped_ptr indexFile_; }; void HelpExportMan::exportModuleHelp(const std::string &tag, @@ -335,11 +458,16 @@ class HelpExportHtml : public HelpExportInterface const CommandLineModuleInterface &module); virtual void finishModuleExport(); + virtual void startModuleGroupExport(); + virtual void exportModuleGroup(const char *title, + const ModuleGroupContents &modules); + virtual void finishModuleGroupExport(); + private: void writeHtmlHeader(File *file, const std::string &title) const; void writeHtmlFooter(File *file) const; - boost::scoped_ptr byNameFile_; + boost::scoped_ptr indexFile_; HelpLinks links_; }; @@ -360,9 +488,9 @@ HelpExportHtml::HelpExportHtml() void HelpExportHtml::startModuleExport() { - byNameFile_.reset(new File("byname.html", "w")); - writeHtmlHeader(byNameFile_.get(), "GROMACS Programs by Name"); - byNameFile_->writeLine("

GROMACS Programs Alphabetically

"); + indexFile_.reset(new File("byname.html", "w")); + writeHtmlHeader(indexFile_.get(), "GROMACS Programs by Name"); + indexFile_->writeLine("

GROMACS Programs Alphabetically

"); } void HelpExportHtml::exportModuleHelp(const std::string &tag, @@ -381,15 +509,45 @@ void HelpExportHtml::exportModuleHelp(const std::string &tag, writeHtmlFooter(&file); file.close(); - byNameFile_->writeLine(formatString("%s - %s
", - tag.c_str(), displayName.c_str(), - module.shortDescription())); + indexFile_->writeLine(formatString("%s - %s
", + tag.c_str(), displayName.c_str(), + module.shortDescription())); } void HelpExportHtml::finishModuleExport() { - writeHtmlFooter(byNameFile_.get()); - byNameFile_->close(); + writeHtmlFooter(indexFile_.get()); + indexFile_->close(); +} + +void HelpExportHtml::startModuleGroupExport() +{ + indexFile_.reset(new File("bytopic.html", "w")); + writeHtmlHeader(indexFile_.get(), "GROMACS Programs by Topic"); + indexFile_->writeLine("

GROMACS Programs by Topic

"); +} + +void HelpExportHtml::exportModuleGroup(const char *title, + const ModuleGroupContents &modules) +{ + indexFile_->writeLine(formatString("

%s

", title)); + + ModuleGroupContents::const_iterator module; + for (module = modules.begin(); module != modules.end(); ++module) + { + const std::string &tag(module->first); + std::string displayName(tag); + std::replace(displayName.begin(), displayName.end(), '-', ' '); + indexFile_->writeLine(formatString("%s - %s
", + tag.c_str(), displayName.c_str(), + module->second)); + } +} + +void HelpExportHtml::finishModuleGroupExport() +{ + writeHtmlFooter(indexFile_.get()); + indexFile_->close(); } void HelpExportHtml::writeHtmlHeader(File *file, const std::string &title) const @@ -451,9 +609,11 @@ class CommandLineHelpModule : public CommandLineModuleInterface * Creates a command-line help module. * * \param[in] modules List of modules for to use for module listings. + * \param[in] groups List of module groups. * \throws std::bad_alloc if out of memory. */ - explicit CommandLineHelpModule(const CommandLineModuleMap &modules); + CommandLineHelpModule(const CommandLineModuleMap &modules, + const CommandLineModuleGroupList &groups); /*! \brief * Adds a top-level help topic. @@ -495,6 +655,7 @@ class CommandLineHelpModule : public CommandLineModuleInterface boost::scoped_ptr rootTopic_; const CommandLineModuleMap &modules_; + const CommandLineModuleGroupList &groups_; CommandLineHelpContext *context_; const CommandLineModuleInterface *moduleOverride_; @@ -503,8 +664,10 @@ class CommandLineHelpModule : public CommandLineModuleInterface GMX_DISALLOW_COPY_AND_ASSIGN(CommandLineHelpModule); }; -CommandLineHelpModule::CommandLineHelpModule(const CommandLineModuleMap &modules) - : rootTopic_(new RootHelpTopic(modules)), modules_(modules), +CommandLineHelpModule::CommandLineHelpModule( + const CommandLineModuleMap &modules, + const CommandLineModuleGroupList &groups) + : rootTopic_(new RootHelpTopic(modules)), modules_(modules), groups_(groups), context_(NULL), moduleOverride_(NULL), bHidden_(false) { } @@ -601,6 +764,14 @@ void CommandLineHelpModule::exportHelp(HelpExportInterface *exporter) const } } exporter->finishModuleExport(); + + exporter->startModuleGroupExport(); + CommandLineModuleGroupList::const_iterator group; + for (group = groups_.begin(); group != groups_.end(); ++group) + { + exporter->exportModuleGroup((*group)->title(), (*group)->modules()); + } + exporter->finishModuleGroupExport(); } namespace @@ -788,6 +959,14 @@ class CommandLineModuleManager::Impl * Owns the contained modules. */ CommandLineModuleMap modules_; + /*! \brief + * List of groupings for modules for help output. + * + * Owns the contained module group data objects. + * CommandLineModuleGroup objects point to the data objects contained + * here. + */ + CommandLineModuleGroupList moduleGroups_; //! Information about the currently running program. ProgramInfo &programInfo_; /*! \brief @@ -831,7 +1010,7 @@ void CommandLineModuleManager::Impl::ensureHelpModuleExists() { if (helpModule_ == NULL) { - helpModule_ = new CommandLineHelpModule(modules_); + helpModule_ = new CommandLineHelpModule(modules_, moduleGroups_); addModule(CommandLineModulePointer(helpModule_)); } } @@ -994,6 +1173,15 @@ void CommandLineModuleManager::addModuleCMain( addModule(move(module)); } +CommandLineModuleGroup CommandLineModuleManager::addModuleGroup( + const char *title) +{ + CommandLineModuleGroupDataPointer group( + new internal::CommandLineModuleGroupData(impl_->modules_, title)); + impl_->moduleGroups_.push_back(move(group)); + return CommandLineModuleGroup(impl_->moduleGroups_.back().get()); +} + void CommandLineModuleManager::addHelpTopic(HelpTopicPointer topic) { impl_->ensureHelpModuleExists(); @@ -1068,4 +1256,19 @@ int CommandLineModuleManager::runAsMainCMain( return runAsMainSingleModule(argc, argv, &module); } +/******************************************************************** + * CommandLineModuleGroup + */ + +void CommandLineModuleGroup::addModule(const char *name) +{ + impl_->addModule(name, NULL); +} + +void CommandLineModuleGroup::addModuleWithDescription(const char *name, + const char *description) +{ + impl_->addModule(name, description); +} + } // namespace gmx diff --git a/src/gromacs/commandline/cmdlinemodulemanager.h b/src/gromacs/commandline/cmdlinemodulemanager.h index c6dcbdcfe9..6324616f60 100644 --- a/src/gromacs/commandline/cmdlinemodulemanager.h +++ b/src/gromacs/commandline/cmdlinemodulemanager.h @@ -50,6 +50,7 @@ namespace gmx { +class CommandLineModuleGroup; class CommandLineModuleInterface; class ProgramInfo; @@ -57,6 +58,11 @@ class ProgramInfo; typedef gmx_unique_ptr::type CommandLineModulePointer; +namespace internal +{ +class CommandLineModuleGroupData; +} // namespace internal + /*! \brief * Implements a wrapper command-line interface for multiple modules. * @@ -235,7 +241,20 @@ class CommandLineModuleManager } /*! \brief - * Make given help topic available through the manager's help module. + * Adds a group for modules to use in help output. + * + * \param[in] title Short title for the group. + * \returns Handle that can be used to add modules to the group. + * \throws std::bad_alloc if out of memory. + * + * Creates a group that is used to structure the list of all modules in + * help output. Modules are added to the group using the returned + * object. + */ + CommandLineModuleGroup addModuleGroup(const char *title); + + /*! \brief + * Makes given help topic available through the manager's help module. * * \param[in] topic Help topic to add. * \throws std::bad_alloc if out of memory. @@ -265,6 +284,58 @@ class CommandLineModuleManager PrivateImplPointer impl_; }; +/*! \brief + * Handle to add content to a group added with + * CommandLineModuleManager::addModuleGroup(). + * + * This class only provides a public interface to construct a module group for + * CommandLineModuleManager, and has semantics similar to a pointer: copies all + * point to the same group. The actual state of the group is maintained in an + * internal implementation class. + * + * \inpublicapi + * \ingroup module_commandline + */ +class CommandLineModuleGroup +{ + public: + /*! \cond internal */ + //! Shorthand for the implementation type that holds all the data. + typedef internal::CommandLineModuleGroupData Impl; + + //! Creates a new group (only called by CommandLineModuleManager). + explicit CommandLineModuleGroup(Impl *impl) : impl_(impl) {} + //! \endcond + + /*! \brief + * Adds a module to this group. + * + * \param[in] name Name of the module. + * \throws std::bad_alloc if out of memory. + * + * This works as addModuleWithDescription(), but uses the short + * description of the module itself as the description. + * + * \see addModuleWithDescription() + */ + void addModule(const char *name); + /*! \brief + * Adds a module to this group with a custom description. + * + * \param[in] name Name of the module. + * \param[in] description Description of the module in this group. + * \throws std::bad_alloc if out of memory. + * + * \p name must name a module added into the CommandLineModuleManager. + * It is possible to add the same module into multiple groups. + */ + void addModuleWithDescription(const char *name, const char *description); + + private: + //! Pointer to the data owned by CommandLineModuleManager. + Impl *impl_; +}; + } // namespace gmx #endif diff --git a/src/gromacs/trajectoryanalysis/modules.cpp b/src/gromacs/trajectoryanalysis/modules.cpp index c45421b4d4..d5d16c124a 100644 --- a/src/gromacs/trajectoryanalysis/modules.cpp +++ b/src/gromacs/trajectoryanalysis/modules.cpp @@ -41,6 +41,7 @@ */ #include "gromacs/trajectoryanalysis/modules.h" +#include "gromacs/commandline/cmdlinemodulemanager.h" #include "gromacs/trajectoryanalysis/cmdlinerunner.h" #include "modules/angle.h" @@ -67,11 +68,13 @@ namespace * \ingroup module_trajectoryanalysis */ template -void registerModule(CommandLineModuleManager *manager) +void registerModule(CommandLineModuleManager *manager, + CommandLineModuleGroup group) { TrajectoryAnalysisCommandLineRunner::registerModule( manager, ModuleInfo::name, ModuleInfo::shortDescription, &ModuleInfo::create); + group.addModule(ModuleInfo::name); } } // namespace @@ -79,10 +82,11 @@ void registerModule(CommandLineModuleManager *manager) void registerTrajectoryAnalysisModules(CommandLineModuleManager *manager) { using namespace gmx::analysismodules; - registerModule(manager); - registerModule(manager); - registerModule(manager); - registerModule(manager); + CommandLineModuleGroup group = manager->addModuleGroup("Trajectory analysis"); + registerModule(manager, group); + registerModule(manager, group); + registerModule(manager, group); + registerModule(manager, group); } } // namespace gmx diff --git a/src/programs/gmx/legacymodules.cpp b/src/programs/gmx/legacymodules.cpp index 9e8ddc0165..f45fb20abe 100644 --- a/src/programs/gmx/legacymodules.cpp +++ b/src/programs/gmx/legacymodules.cpp @@ -222,7 +222,7 @@ void registerLegacyModules(gmx::CommandLineModuleManager *manager) registerModule(manager, &gmx_covar, "covar", "Calculate and diagonalize the covariance matrix"); registerModule(manager, &gmx_current, "current", - "Calculate dielectric constants and charge autocorrelation function"); + "Calculate dielectric constants and current autocorrelation function"); registerModule(manager, &gmx_density, "density", "Calculate the density of the system"); registerModule(manager, &gmx_densmap, "densmap", @@ -305,11 +305,11 @@ void registerLegacyModules(gmx::CommandLineModuleManager *manager) registerModule(manager, &gmx_saltbr, "saltbr", "Compute salt bridges"); registerModule(manager, &gmx_sans, "sans", - "Compute the small angle neutron scattering spectra"); + "Compute small angle neutron scattering spectra"); registerModule(manager, &gmx_sas, "sas", "Compute solvent accessible surface area"); registerModule(manager, &gmx_saxs, "saxs", - "Calculates SAXS structure factors based on Cromer's method"); + "Compute small angle X-ray scattering spectra"); registerModule(manager, &gmx_sham, "sham", "Compute free energies or other histograms from histograms"); registerModule(manager, &gmx_sigeps, "sigeps", @@ -327,7 +327,7 @@ void registerLegacyModules(gmx::CommandLineModuleManager *manager) registerModule(manager, &gmx_tune_pme, "tune_pme", "Time mdrun as a function of PME nodes to optimize settings"); registerModule(manager, &gmx_vanhove, "vanhove", - "Compute Van Hove correlation functions"); + "Compute Van Hove displacement and correlation functions"); registerModule(manager, &gmx_velacc, "velacc", "Calculate velocity autocorrelation functions"); registerModule(manager, &gmx_wham, "wham", @@ -337,7 +337,182 @@ void registerLegacyModules(gmx::CommandLineModuleManager *manager) registerModule(manager, &gmx_view, "view", "View a trajectory on an X-Windows terminal"); - // TODO: Also include binaries from other directories than src/tools/: - // "mdrun|finds a potential energy minimum and calculates the Hessian"); - // "mdrun|with -rerun (re)calculates energies for trajectory frames"); + { + gmx::CommandLineModuleGroup group = + manager->addModuleGroup("Generating topologies and coordinates"); + group.addModuleWithDescription("editconf", "Edit the box and write subgroups"); + group.addModule("protonate"); + group.addModule("x2top"); + group.addModule("genbox"); + group.addModule("genconf"); + group.addModule("genion"); + group.addModule("genrestr"); + group.addModule("pdb2gmx"); + } + { + gmx::CommandLineModuleGroup group = + manager->addModuleGroup("Running a simulation"); + group.addModule("grompp"); + group.addModule("mdrun"); + group.addModule("tpbconv"); + } + { + gmx::CommandLineModuleGroup group = + manager->addModuleGroup("Viewing trajectories"); + group.addModule("nmtraj"); + group.addModule("view"); + } + { + gmx::CommandLineModuleGroup group = + manager->addModuleGroup("Processing energies"); + group.addModule("enemat"); + group.addModule("energy"); + group.addModuleWithDescription("mdrun", "(Re)calculate energies for trajectory frames with -rerun"); + } + { + gmx::CommandLineModuleGroup group = + manager->addModuleGroup("Converting files"); + group.addModule("editconf"); + group.addModule("eneconv"); + group.addModule("sigeps"); + group.addModule("trjcat"); + group.addModule("trjconv"); + group.addModule("xpm2ps"); + } + { + gmx::CommandLineModuleGroup group = + manager->addModuleGroup("Tools"); + group.addModule("analyze"); + group.addModule("dyndom"); + group.addModule("filter"); + group.addModule("lie"); + group.addModule("morph"); + group.addModule("pme_error"); + group.addModule("sham"); + group.addModule("spatial"); + group.addModule("traj"); + group.addModule("tune_pme"); + group.addModule("wham"); + group.addModule("check"); + group.addModule("dump"); + group.addModule("make_ndx"); + group.addModule("mk_angndx"); + group.addModule("trjorder"); + group.addModule("xpm2ps"); + } + { + gmx::CommandLineModuleGroup group = + manager->addModuleGroup("Distances between structures"); + group.addModule("cluster"); + group.addModule("confrms"); + group.addModule("rms"); + group.addModule("rmsf"); + } + { + gmx::CommandLineModuleGroup group = + manager->addModuleGroup("Distances in structures over time"); + group.addModule("mindist"); + group.addModule("mdmat"); + group.addModule("polystat"); + group.addModule("rmsdist"); + } + { + gmx::CommandLineModuleGroup group = + manager->addModuleGroup("Mass distribution properties over time"); + group.addModule("gyrate"); + group.addModule("msd"); + group.addModule("polystat"); + group.addModule("rdf"); + group.addModule("rotacf"); + group.addModule("rotmat"); + group.addModule("sans"); + group.addModule("saxs"); + group.addModule("traj"); + group.addModule("vanhove"); + } + { + gmx::CommandLineModuleGroup group = + manager->addModuleGroup("Analyzing bonded interactions"); + group.addModule("angle"); + group.addModule("mk_angndx"); + } + { + gmx::CommandLineModuleGroup group = + manager->addModuleGroup("Structural properties"); + group.addModule("anadock"); + group.addModule("bundle"); + group.addModule("clustsize"); + group.addModule("disre"); + group.addModule("hbond"); + group.addModule("order"); + group.addModule("principal"); + group.addModule("rdf"); + group.addModule("saltbr"); + group.addModule("sas"); + group.addModule("sorient"); + group.addModule("spol"); + } + { + gmx::CommandLineModuleGroup group = + manager->addModuleGroup("Kinetic properties"); + group.addModule("bar"); + group.addModule("current"); + group.addModule("dos"); + group.addModule("dyecoupl"); + group.addModule("kinetics"); + group.addModule("principal"); + group.addModule("tcaf"); + group.addModule("traj"); + group.addModule("vanhove"); + group.addModule("velacc"); + } + { + gmx::CommandLineModuleGroup group = + manager->addModuleGroup("Electrostatic properties"); + group.addModule("current"); + group.addModule("dielectric"); + group.addModule("dipoles"); + group.addModule("potential"); + group.addModule("spol"); + group.addModule("genion"); + } + { + gmx::CommandLineModuleGroup group = + manager->addModuleGroup("Protein-specific analysis"); + group.addModule("do_dssp"); + group.addModule("chi"); + group.addModule("helix"); + group.addModule("helixorient"); + group.addModule("rama"); + group.addModule("wheel"); + } + { + gmx::CommandLineModuleGroup group = + manager->addModuleGroup("Interfaces"); + group.addModule("bundle"); + group.addModule("density"); + group.addModule("densmap"); + group.addModule("densorder"); + group.addModule("h2order"); + group.addModule("hydorder"); + group.addModule("order"); + group.addModule("potential"); + } + { + gmx::CommandLineModuleGroup group = + manager->addModuleGroup("Covariance analysis"); + group.addModuleWithDescription("anaeig", "Analyze the eigenvectors"); + group.addModule("covar"); + group.addModule("make_edi"); + } + { + gmx::CommandLineModuleGroup group = + manager->addModuleGroup("Normal modes"); + group.addModuleWithDescription("anaeig", "Analyze the normal modes"); + group.addModule("nmeig"); + group.addModule("nmtraj"); + group.addModule("nmens"); + group.addModule("grompp"); + group.addModuleWithDescription("mdrun", "Find a potential energy minimum and calculate the Hessian"); + } }