- Add documentation for some partially documented classes.
- Some fixes to cosmetic issues in surrounding code that were noticed.
- Some other clean-up.
There are a few warnings in pre-5.0 C code that are not addressed here.
Of the remaining warnings, quite a few are are either in obsolete code
(template.c, displacement.c), or in code that should be heavily
refactored (nbsearch.h, issue #866).
Change-Id: I7c309153769f35e93c4d0ff28667663e6a9e8ee3
protected:
/*! \cond libapi */
AbstractPlotModule();
- //! Creates AbstractPlotModule and assign common settings for the plotting
+ //! Creates AbstractPlotModule and assign common settings.
explicit AbstractPlotModule(const AnalysisDataPlotSettings &settings);
+ //! Whether an output file has been opened.
bool isFileOpen() const;
+ /*! \brief
+ * Appends a single value to the current output line.
+ *
+ * \param[in] value Value to append.
+ *
+ * Should be used from pointsAdded() implementations in derived classes
+ * to write out individual y values to the output.
+ *
+ * Must not be called if isFileOpen() returns false.
+ */
void writeValue(real value) const;
//! \endcond
{
public:
AnalysisDataPlotModule();
- //! Creates AnalysisDataPlotModule and assign common settings for the plotting
+ //! Creates AnalysisDataPlotModule and assign common settings.
explicit AnalysisDataPlotModule(const AnalysisDataPlotSettings &settings);
virtual void pointsAdded(const AnalysisDataPointSetRef &points);
{
public:
AnalysisDataVectorPlotModule();
- //! Creates AnalysisDataVectorPlotModule and assign common settings for the plotting
+ //! Creates AnalysisDataVectorPlotModule and assign common settings.
explicit AnalysisDataVectorPlotModule(const AnalysisDataPlotSettings &settings);
/*! \brief
* Use of error return codes should be avoided in new code except in C wrappers
* and similar, but for compatibility, facilities for handling them are
* provided by the errorcodes.h header file. It provides a set of error codes
- * (the enum ::ErrorCode) that should be used for return codes in functions.
+ * (the enum \ref gmx::ErrorCode) that should be used for return codes in functions.
* It also provides macros ::GMX_ERROR and ::GMX_ERROR_NORET that should be
* used for returning an error code. setFatalErrorHandler() is provided to
* alter the behavior of ::GMX_ERROR and ::GMX_ERROR_NORET. The default
class BooleanOptionInfo : public OptionInfo
{
public:
+ //! Creates an option info object for the given option.
explicit BooleanOptionInfo(BooleanOptionStorage *option);
};
class IntegerOptionInfo : public OptionInfo
{
public:
+ //! Creates an option info object for the given option.
explicit IntegerOptionInfo(IntegerOptionStorage *option);
};
class DoubleOptionInfo : public OptionInfo
{
public:
+ //! Creates an option info object for the given option.
explicit DoubleOptionInfo(DoubleOptionStorage *option);
- //! Whether the option provides a time value.
+ //! Whether the option specifies a time value.
bool isTime() const;
/*! \brief
class StringOptionInfo : public OptionInfo
{
public:
+ //! Creates an option info object for the given option.
explicit StringOptionInfo(StringOptionStorage *option);
};
class FileNameOptionInfo : public OptionInfo
{
public:
+ //! Creates an option info object for the given option.
explicit FileNameOptionInfo(FileNameOptionStorage *option);
+ //! Whether the option specifies an input file.
bool isInputFile() const;
+ //! Whether the option specifies an output file.
bool isOutputFile() const;
+ //! Whether the option specifies a file used for both input and output.
bool isInputOutputFile() const;
+ /*! \brief
+ * Whether the option specifies a library file.
+ *
+ * \see FileNameOption::libraryFile()
+ */
bool isLibraryFile() const;
private:
virtual const char *typeString() const;
virtual std::string formatValue(int i) const;
+ //! \copydoc DoubleOptionInfo::isTime()
bool isTime() const { return bTime_; }
+ //! \copydoc DoubleOptionInfo::setScaleFactor()
void setScaleFactor(double factor);
private:
virtual const char *typeString() const { return "file"; }
virtual std::string formatValue(int i) const;
+ //! \copydoc FileNameOptionInfo::isInputFile()
bool isInputFile() const { return bRead_ && !bWrite_; }
+ //! \copydoc FileNameOptionInfo::isOutputFile()
bool isOutputFile() const { return !bRead_ && bWrite_; }
+ //! \copydoc FileNameOptionInfo::isInputOutputFile()
bool isInputOutputFile() const { return bRead_ && bWrite_; }
+ //! \copydoc FileNameOptionInfo::isLibraryFile()
bool isLibraryFile() const { return bLibrary_; }
private:
namespace gmx
{
-/*! \internal \brief
+/*! \cond libapi */
+/*! \libinternal \brief
* Flags for options.
*
* These flags are not part of the public interface, even though they are in an
//efAtomVal = 1<<21,
};
-//! Holds a combination of ::OptionFlag values.
+//! \libinternal Holds a combination of ::OptionFlag values.
typedef FlagsTemplate<OptionFlag> OptionFlags;
+//! \endcond
} // namespace gmx
std::string formatValues() const;
protected:
+ /*! \cond libapi */
/*! \brief
* Wraps a given option object.
*/
explicit OptionInfo(AbstractOptionStorage *option);
+ //! Returns the wrapped option storage object.
AbstractOptionStorage &option() { return _option; }
+ //! Returns the wrapped option storage object.
const AbstractOptionStorage &option() const { return _option; }
+ //! \endcond
private:
//! The wrapped option.
* OptionInfo
*/
+/*! \cond libapi */
OptionInfo::OptionInfo(AbstractOptionStorage *option)
: _option(*option)
{
}
+//! \endcond
OptionInfo::~OptionInfo()
{
* Time values for TimeUnitManager.
*
* \if internal
- * Currently, this should match with the ::time_unit_t enum defined in oenv.h
+ * Currently, this should match with the time_unit_t enum defined in oenv.h
* except that there is no NULL first item in this enum.
* \endif
*
#include "selectioncollection-impl.h"
#include "selelem.h"
+namespace
+{
+
/*! \internal \brief
* Reserves memory for a selection element from the evaluation memory pool.
+ *
+ * This class implements RAII semantics for allocating memory for selection
+ * element values from a selection evaluation memory pool.
+ *
+ * \ingroup module_selection
*/
class MempoolSelelemReserver
{
public:
+ //! Constructs a reserver without initial reservation.
MempoolSelelemReserver() : sel_(NULL) {}
+ /*! \brief
+ * Constructs a reserver with initial reservation.
+ *
+ * \param[in,out] sel Selection element for which to reserve.
+ * \param[in] count Number of values to reserve.
+ *
+ * \see reserve()
+ */
MempoolSelelemReserver(t_selelem *sel, int count)
: sel_(NULL)
{
reserve(sel, count);
}
+ //! Frees any memory allocated using this reserver.
~MempoolSelelemReserver()
{
if (sel_ != NULL)
}
}
+ /*! \brief
+ * Reserves memory for selection element values using this reserver.
+ *
+ * \param[in,out] sel Selection element for which to reserve.
+ * \param[in] count Number of values to reserve.
+ *
+ * Allocates space to store \p count output values in \p sel from the
+ * memory pool associated with \p sel, or from the heap if there is no
+ * memory pool. Type of values to allocate is automatically determined
+ * from \p sel.
+ */
void reserve(t_selelem *sel, int count)
{
GMX_RELEASE_ASSERT(sel_ == NULL, "Can only reserve one element with one instance");
/*! \internal \brief
* Reserves memory for an index group from the evaluation memory pool.
+ *
+ * This class implements RAII semantics for allocating memory for an index
+ * group from a selection evaluation memory pool.
+ *
+ * \ingroup module_selection
*/
class MempoolGroupReserver
{
public:
+ /*! \brief
+ * Creates a reserver associated with a given memory pool.
+ *
+ * \param mp Memory pool from which to reserve memory.
+ */
explicit MempoolGroupReserver(gmx_sel_mempool_t *mp)
: mp_(mp), g_(NULL)
{
}
+ //! Frees any memory allocated using this reserver.
~MempoolGroupReserver()
{
if (g_ != NULL)
}
}
+ /*! \brief
+ * Reserves memory for an index group using this reserver.
+ *
+ * \param[in,out] g Index group to reserve.
+ * \param[in] count Number of atoms to reserve space for.
+ *
+ * Allocates memory from the memory pool to store \p count atoms in
+ * \p g.
+ */
void reserve(gmx_ana_index_t *g, int count)
{
GMX_RELEASE_ASSERT(g_ == NULL, "Can only reserve one element with one instance");
/*! \internal \brief
* Assigns a temporary value for a selection element.
+ *
+ * This class implements RAII semantics for temporarily assigning the value
+ * pointer of a selection element to point to a different location.
+ *
+ * \ingroup module_selection
*/
class SelelemTemporaryValueAssigner
{
public:
+ //! Constructs an assigner without an initial assignment.
SelelemTemporaryValueAssigner()
: sel_(NULL), old_ptr_(NULL), old_nalloc_(0)
{
}
+ /*! \brief
+ * Constructs an assigner with an initial assignment.
+ *
+ * \param[in,out] sel Selection element for which to assign.
+ * \param[in] vsource Element to which \p sel values will point to.
+ *
+ * \see assign()
+ */
SelelemTemporaryValueAssigner(t_selelem *sel, t_selelem *vsource)
: sel_(NULL)
{
assign(sel, vsource);
}
+ //! Undoes any temporary assignment done using this assigner.
~SelelemTemporaryValueAssigner()
{
if (sel_ != NULL)
}
}
+ /*! \brief
+ * Assigns a temporary value pointer.
+ *
+ * \param[in,out] sel Selection element for which to assign.
+ * \param[in] vsource Element to which \p sel values will point to.
+ *
+ * Assigns the value pointer in \p sel to point to the values in
+ * \p vsource, i.e., any access/modification to values in \p sel
+ * actually accesses values in \p vsource.
+ */
void assign(t_selelem *sel, t_selelem *vsource)
{
- GMX_RELEASE_ASSERT(sel_ == NULL, "Can only assign one element with one instance");
+ GMX_RELEASE_ASSERT(sel_ == NULL,
+ "Can only assign one element with one instance");
+ GMX_RELEASE_ASSERT(sel->v.type == vsource->v.type,
+ "Mismatching selection value types");
old_ptr_ = sel->v.u.ptr;
old_nalloc_ = sel->v.nalloc;
_gmx_selvalue_setstore(&sel->v, vsource->v.u.ptr);
int old_nalloc_;
};
+} // namespace
+
/*!
* \param[in] fp File handle to receive the output.
* \param[in] evalfunc Function pointer to print.
"dyn_mol_com", "dyn_mol_cog",
NULL,
};
-//! Number of elements in ::poscalc_enum_strings.
+//! Number of elements in poscalc_enum_strings.
#define NENUM asize(poscalc_enum_strings)
/*! \brief
//! Deprecated method for direct access to atom index data.
gmx_ana_index_t *indexGroup() const { return rawPositions_.g; }
+ // TODO: Remove direct access to the flags from the public interface.
//! Returns true if the given flag is set.
bool hasFlag(SelectionFlag flag) const { return flags_.test(flag); }
//! Sets the flags for this selection.
{
public:
/*! \brief
+ * Constructs a wrapper object for given selection position.
+ *
+ * \param[in] sel Selection from which the position is wrapped.
+ * \param[in] index Zero-based index of the position to wrap.
+ *
+ * Does not throw. Asserts if \p index is out of range.
*/
SelectionPosition(const Selection *sel, int index)
: sel_(sel), i_(index)
* across frames. After compilation, these IDs are consequently
* numbered starting from zero. For each frame, the ID then reflects
* the location of the position in the original array of positions.
- * If ::efDynamicMask has been set for the parent selection, the IDs
- * for positions not present in the current selection are set to
- * -1, otherwise they are removed completely.
+ * If SelectionOption::dynamicMask() has been set for the parent
+ * selection, the IDs for positions not present in the current
+ * selection are set to -1, otherwise they are removed completely.
*
* Example:
* If a dynamic selection consists of three positions, after
* compilation refId() will return 0, 1, 2 for them, respectively.
* If for a particular frame, only the first and the third are present,
* refId() will return 0, 2.
- * If ::efDynamicMask has been set, all three positions can be accessed
- * also in this case and refId() will return 0, -1, 2.
+ * If SelectionOption::dynamicMask() has been set, all three positions
+ * can be accessed also in this case and refId() will return 0, -1, 2.
*/
int refId() const
{
#include "../legacyheaders/typedefs.h"
-#include "gromacs/utility/uniqueptr.h"
-
#include "../options/options.h"
#include "../utility/flags.h"
+#include "../utility/uniqueptr.h"
#include "indexutil.h"
#include "selectioncollection.h"
{
}
+ /*! \brief
+ * Returns the number of selections requested in this request.
+ *
+ * -1 indicates no upper limit.
+ */
int count() const;
std::string name;
*/
void runParser(void *scanner, int maxnr,
std::vector<Selection *> *output);
+ /*! \brief
+ * Adds a selection request for delayed user input.
+ *
+ * \param[in] name Name for the requested selections.
+ * \param[in] descr Description of the requested selections.
+ * \param storage Storage object to receive the selections.
+ *
+ * \see parseRequestedFromStdin()
+ */
void requestSelections(const std::string &name,
const std::string &descr,
SelectionOptionStorage *storage);
+ /*! \brief
+ * Replace group references by group contents.
+ *
+ * \param[in] root Root of selection tree to process.
+ * \param errors Object for reporting any error messages.
+ *
+ * Recursively searches the selection tree for unresolved external
+ * references. If one is found, finds the referenced group in
+ * \a _grps and replaces the reference with a constant element that
+ * contains the atoms from the referenced group. Any failures to
+ * resolve references are reported to \p errors.
+ */
void resolveExternalGroups(struct t_selelem *root,
MessageStringCollector *errors);
namespace gmx
{
-/*! \brief
+/*! \cond internal */
+/*! \internal \brief
* Flags for options.
*
* These flags are not part of the public interface, even though they are in an
efEvaluateForces = 1<<6,
};
-//! Holds a collection of ::SelectionFlag values.
+//! \internal Holds a collection of ::SelectionFlag values.
typedef FlagsTemplate<SelectionFlag> SelectionFlags;
+//! \endcond
}
} // namespace
+/*! \cond libapi */
void setSelectionCollectionForOptions(Options *options,
SelectionCollection *selections)
{
SelectionCollectionSetter(selections).visitSubSection(options);
}
+//! \endcond
} // namespace gmx
/*! \brief
* Handle dynamic selections for this option with position masks.
*
+ * \if internal
* Sets ::POS_MASKONLY on the positions for this selection.
+ * \endif
*/
MyClass &dynamicMask()
{ _selectionFlags.set(efDynamicMask); return me(); }
const SelectionOptionStorage &option() const;
};
+/*! \cond libapi */
/*! \libinternal \brief
* Set selection collection for all selection options.
*
*/
void setSelectionCollectionForOptions(Options *options,
SelectionCollection *selections);
+//! \endcond
} // namespace gmx
virtual const char *typeString() const { return "sel"; }
virtual std::string formatValue(int i) const;
+ //! \copydoc SelectionOptionInfo::setSelectionCollection()
void setSelectionCollection(SelectionCollection *selections)
{
_sc = selections;
char *s;
} u;
} *m;
+ /**< Array of strings/regular expressions to match against.*/
} t_methoddata_kwstr;
/** Parameters for integer keyword evaluation. */
class TrajectoryAnalysisModuleDataBasic : public TrajectoryAnalysisModuleData
{
public:
+ /*! \brief
+ * Initializes thread-local storage for data handles and selections.
+ *
+ * \param[in] module Analysis module to use for data objects.
+ * \param[in] opt Data parallelization options.
+ * \param[in] selections Thread-local selection collection.
+ */
TrajectoryAnalysisModuleDataBasic(TrajectoryAnalysisModule *module,
const AnalysisDataParallelOptions &opt,
const SelectionCollection &selections);
//! Initializes the default values for the settings object.
Impl() : flags(0), frflags(0), bRmPBC(true), bPBC(true) {}
+ //! Global time unit setting for the analysis module.
TimeUnitManager timeUnitManager;
+ //! Global plotting settings for the analysis module.
AnalysisDataPlotSettings plotSettings;
+ //! Flags for the analysis module.
unsigned long flags;
+ //! Frame reading flags for the analysis module.
int frflags;
+ //! Whether to make molecules whole for each frame.
bool bRmPBC;
+ //! Whether to pass PBC information to the analysis module.
bool bPBC;
};
*
* If called in TrajectoryAnalysisModule::initOptions(), this function
* sets the default for whether PBC are used in the analysis.
- * If ::efNoUserPBC is not set, a command-line option is provided
+ * If \ref efNoUserPBC is not set, a command-line option is provided
* for the user to override the default value.
* If called later, it overrides the setting provided by the user or an
* earlier call.
* TrajectoryAnalysisModule::analyzeFrame() is NULL.
* The value of the flag can also be accessed with hasPBC().
*
- * \see ::efNoUserPBC
+ * \see efNoUserPBC
*/
void setPBC(bool bPBC);
/*! \brief
*
* If called in TrajectoryAnalysisModule::initOptions(), this function
* sets the default for whether molecules are made whole.
- * If ::efNoUserRmPBC is not set, a command-line option is provided
+ * If \ref efNoUserRmPBC is not set, a command-line option is provided
* for the user to override the default value.
* If called later, it overrides the setting provided by the user or an
* earlier call.
* The main use of this function is to call it with \c false if your
* analysis program does not require whole molecules as this can
* increase the performance.
- * In such a case, you can also specify ::efNoUserRmPBC to not to
+ * In such a case, you can also specify \ref efNoUserRmPBC to not to
* confuse the user with an option that would only slow the program
* down.
*
- * \see ::efNoUserRmPBC
+ * \see efNoUserRmPBC
*/
void setRmPBC(bool bRmPBC);
/*! \brief
namespace analysismodules
{
+namespace
+{
+
/*! \internal \brief
* Data module for writing index files.
*
IndexFileWriterModule();
virtual ~IndexFileWriterModule();
+ //! Sets the file name to write the index file to.
void setFileName(const std::string &fnm);
void addGroup(const std::string &name, bool bDynamic);
closeFile();
}
+} // namespace
+
/********************************************************************
* Select::ModuleData
*/
enum HelpFlag
{
- efHelpShowOptions = 1<<0,
- efHelpShowHidden = 1<<1,
- efHelpShowDescriptions = 1<<2,
+ efHelpShowOptions = 1<<0, //!< Show options.
+ efHelpShowHidden = 1<<1, //!< Show hidden options.
+ efHelpShowDescriptions = 1<<2 //!< Show detailed description.
};
- //! Combination of ::HelpFlag values.
+ //! Combination of \ref HelpFlag values.
typedef unsigned long HelpFlags;
+ /*! \brief
+ * Initializes a new runner helper.
+ *
+ * \param settings Settings object to use.
+ */
explicit TrajectoryAnalysisRunnerCommon(TrajectoryAnalysisSettings *settings);
~TrajectoryAnalysisRunnerCommon();
+ //! Initializes common options for trajectory analysis.
Options &initOptions();
+ //! Scales time option values according to the time unit set.
void scaleTimeOptions(Options *options);
+ /*! \brief
+ * Processes common option values after they have been parsed.
+ *
+ * \returns false if the tool should exit after printing help.
+ */
bool initOptionsDone();
+ //! Initialize index groups for selections.
void initIndexGroups(SelectionCollection *selections);
+ //! Free memory allocated for index groups.
void doneIndexGroups(SelectionCollection *selections);
+ //! Load topology information if provided and/or required.
void initTopology(SelectionCollection *selections);
+ /*! \brief
+ * Reads the first frame from the trajectory.
+ *
+ * After this call, frame() returns the first frame.
+ */
void initFirstFrame();
+ /*! \brief
+ * Reads the next frame from the trajectory.
+ *
+ * \returns false if there were no more frames.
+ *
+ * After this call, frame() returns the newly loaded frame.
+ */
bool readNextFrame();
+ /*! \brief
+ * Performs common initialization for the currently loaded frame.
+ *
+ * Currently, makes molecules whole if requested.
+ */
void initFrame();
//! Returns flags for help printing.
class ConstArrayRef
{
public:
+ //! Type of values stored in the container.
typedef T value_type;
+ //! Type for representing size of the container.
typedef size_t size_type;
+ //! Type for representing difference between two container indices.
typedef ptrdiff_t difference_type;
+ //! Const reference to a container element.
typedef const T &const_reference;
+ //! Const pointer to a container element.
typedef const T *const_pointer;
+ //! Const iterator type for the container.
typedef const T *const_iterator;
//! Equal to \a const_reference since changes are not allowed.
typedef const_reference reference;
{
}
+ //! Returns an interator to the beginning of the container.
const_iterator begin() const { return begin_; }
+ //! Returns an interator to the end of the container.
const_iterator end() const { return end_; }
+ //! Returns an interator to the reverse beginning of the container.
const_iterator rbegin() const { return reverse_iterator(end()); }
+ //! Returns an interator to the reverse end of the container.
const_iterator rend() const { return reverse_iterator(begin()); }
+ //! Returns the size of the container.
size_type size() const { return end_ - begin_; }
+ //! Identical to size().
size_type capacity() const { return end_ - begin_; }
+ //! Whether the container is empty.
bool empty() const { return begin_ == end_; }
+ //! Access container element.
const_reference operator[](size_type n) const { return begin_[n]; }
+ //! Access container element (throws on out-of-range error).
const_reference at(size_type n) const
{
if (n >= size())
}
return begin_[n];
}
+ //! Returns the first element in the container.
const_reference front() const { return *begin_; }
+ //! Returns the last element in the container.
const_reference back() const { return *(end_ - 1); }
/*! \brief
#include <boost/scoped_ptr.hpp>
+/*! \cond libapi */
/*! \libinternal \brief
* Macro to declare a class non-copyable and non-assignable.
*
#define GMX_DISALLOW_ASSIGN(ClassName) \
private: \
ClassName &operator =(const ClassName &)
+//! \endcond
namespace gmx
{
/*! \libinternal \brief
* Helper class to manage a pointer to a private implementation class.
*
- * This helper provides the following benefits (the first two could also be
+ * This helper provides the following benefits (all but the last could also be
* achieved with boost::scoped_ptr):
* - Automatic memory management: the implementation pointer is freed in
* the destructor automatically. If the destructor is not declared or is
* defined inline in the header file, a compilation error occurs instead
* of a memory leak or undefined behavior.
+ * - Exception safety in constructors: the implementation pointer is freed
+ * correctly even if the constructor of the containing class throws after
+ * the implementation class is constructed.
* - Copy and/or assignment is automatically disallowed if explicit copy
* constructor and/or assignment operator is not provided.
* - Compiler helps to manage const-correctness: in const methods, it is not
explicit PrivateImplPointer(Impl *ptr) : ptr_(ptr) {}
~PrivateImplPointer() {}
+ /*! \brief
+ * Sets a new implementation class and destructs the previous one.
+ *
+ * Needed, e.g., to implement assignable classes.
+ */
void reset(Impl *ptr) { ptr_.reset(ptr); }
+ //! Access the raw pointer.
Impl *get() { return ptr_.get(); }
+ //! Access the implementation class as with a raw pointer.
Impl *operator->() { return ptr_.get(); }
+ //! Access the implementation class as with a raw pointer.
Impl &operator*() { return *ptr_; }
+ //! Access the raw pointer.
const Impl *get() const { return ptr_.get(); }
+ //! Access the implementation class as with a raw pointer.
const Impl *operator->() const { return ptr_.get(); }
+ //! Access the implementation class as with a raw pointer.
const Impl &operator*() const { return *ptr_; }
private:
class OpenMMData
{
public:
- System* system; /*! The system to simulate. */
- Context* context; /*! The OpenMM context in which the simulation is carried out. */
- Integrator* integrator; /*! The integrator used in the simulation. */
- gmx_bool removeCM; /*! If \true remove venter of motion, false otherwise. */
- GmxOpenMMPlatformOptions *platformOpt; /*! Platform options. */
+ System* system; //!< The system to simulate.
+ Context* context; //!< The OpenMM context in which the simulation is carried out.
+ Integrator* integrator; //!< The integrator used in the simulation.
+ gmx_bool removeCM; //!< If true, remove center of mass motion, false otherwise.
+ GmxOpenMMPlatformOptions *platformOpt; //!< Platform options.
};
/*!
* \inlibraryapi
* \ingroup module_testutils
*/
-/*! \defgroup module_testutils Unit Testing Utility Modules
+/*! \libinternal \defgroup module_testutils Unit Testing Utility Modules
* \brief
* Common helper classes and functions for writing unit tests.
*
*/
void setTestDataPath(const char *path);
-/*!\}*/
-
} // namespace test
} // namespace gmx